# Appendix : Codebase Navigation Guide

### Introduction

This appendix provides a comprehensive guide to navigating rippled's cryptographic code. You'll learn where to find specific implementations, how files are organized, and which functions are most important to understand.

### Directory Structure

```
rippled/
├── include/xrpl/              # Public headers
│   ├── protocol/
│   │   ├── SecretKey.h        # Secret key class
│   │   ├── PublicKey.h        # Public key class
│   │   ├── digest.h           # Hash functions
│   │   ├── KeyType.h          # Key type enumeration
│   │   └── AccountID.h        # Account identifier
│   └── crypto/
│       ├── csprng.h           # CSPRNG interface
│       └── secure_erase.h     # Secure memory erasure
│
├── src/libxrpl/               # Core library implementation
│   ├── protocol/
│   │   ├── SecretKey.cpp      # Key generation, signing (404 lines)
│   │   ├── PublicKey.cpp      # Verification, canonicality (328 lines)
│   │   ├── digest.cpp         # Hash implementations (109 lines)
│   │   ├── AccountID.cpp      # Account ID utilities
│   │   └── tokens.cpp         # Base58 encoding/decoding
│   ├── crypto/
│   │   ├── csprng.cpp         # CSPRNG implementation (110 lines)
│   │   ├── secure_erase.cpp   # Memory wiping (35 lines)
│   │   └── RFC1751.cpp        # Mnemonic words
│   └── basics/
│       └── make_SSLContext.cpp # SSL/TLS configuration
│
└── src/xrpld/                 # Daemon-specific code
    ├── app/tx/impl/
    │   └── Transactor.cpp     # Transaction signature validation
    ├── app/ledger/
    │   └── LedgerMaster.cpp   # Ledger management
    └── overlay/detail/
        └── Handshake.cpp      # Peer cryptographic handshake
```

### Core Cryptographic Files

#### 1. SecretKey.cpp (404 lines)

**Location:** `src/libxrpl/protocol/SecretKey.cpp`

**Key functions:**

```
// Random key generation
SecretKey randomSecretKey();

// Deterministic key generation
SecretKey generateSecretKey(KeyType type, Seed const& seed);
std::pair<PublicKey, SecretKey> generateKeyPair(KeyType type, Seed const& seed);

// Public key derivation
PublicKey derivePublicKey(KeyType type, SecretKey const& sk);

// Signing
Buffer sign(PublicKey const& pk, SecretKey const& sk, Slice const& m);
Buffer signDigest(PublicKey const& pk, SecretKey const& sk, uint256 const& digest);
```

**Navigate to:**

* Line \~50: `randomSecretKey()` implementation
* Line \~100: `generateKeyPair()` for secp256k1
* Line \~150: `generateKeyPair()` for ed25519
* Line \~200: `derivePublicKey()` implementations
* Line \~300: `sign()` function

#### 2. PublicKey.cpp (328 lines)

**Location:** `src/libxrpl/protocol/PublicKey.cpp`

**Key functions:**

```
// Verification
bool verify(PublicKey const& pk, Slice const& m, Slice const& sig, bool canonical);
bool verifyDigest(PublicKey const& pk, uint256 const& digest, Slice const& sig, bool canonical);

// Canonicality checking
std::optional<ECDSACanonicality> ecdsaCanonicality(Slice const& sig);
bool ed25519Canonical(Slice const& sig);

// Key type detection
std::optional<KeyType> publicKeyType(Slice const& slice);
```

**Navigate to:**

* Line \~50: `verify()` function
* Line \~120: `verifyDigest()` for secp256k1
* Line \~180: Ed25519 verification
* Line \~240: `ecdsaCanonicality()` implementation

#### 3. digest.cpp (109 lines)

**Location:** `src/libxrpl/protocol/digest.cpp`

**Key implementations:**

```
// SHA-512-Half hasher
class sha512_half_hasher { /* ... */ };

// RIPESHA hasher
class ripesha_hasher { /* ... */ };

// Helper functions
uint256 sha512Half(Args const&... args);
uint256 sha512Half_s(Slice const& data);  // Secure variant
```

**Navigate to:**

* Line \~20: `sha512_half_hasher` class
* Line \~50: `ripesha_hasher` class
* Line \~80: Utility functions

#### 4. csprng.cpp (110 lines)

**Location:** `src/libxrpl/crypto/csprng.cpp`

**Key implementation:**

```
class csprng_engine {
    // Constructor: Initialize entropy
    // operator(): Generate random bytes
    // mix_entropy(): Add additional entropy
};

csprng_engine& crypto_prng();  // Global singleton
```

**Navigate to:**

* Line \~30: `csprng_engine` class definition
* Line \~50: Constructor (entropy initialization)
* Line \~70: `operator()` (random byte generation)
* Line \~90: `mix_entropy()` (additional entropy)

#### 5. tokens.cpp

**Location:** `src/libxrpl/protocol/tokens.cpp`

**Key functions:**

```
// Base58Check encoding
std::string encodeBase58Token(TokenType type, void const* token, std::size_t size);

// Base58Check decoding
std::string decodeBase58Token(std::string const& s, TokenType type);

// Helpers
std::string toBase58(AccountID const& id);
std::optional<AccountID> parseBase58(std::string const& s);
```

### Finding Specific Functionality

#### "Where is...?"

**Key generation:**

```
src/libxrpl/protocol/SecretKey.cpp
  → randomSecretKey()          // Random generation
  → generateKeyPair()          // Deterministic from seed
```

**Signing:**

```
src/libxrpl/protocol/SecretKey.cpp
  → sign()                     // Sign message
  → signDigest()               // Sign pre-hashed message
```

**Verification:**

```
src/libxrpl/protocol/PublicKey.cpp
  → verify()                   // Verify signature
  → verifyDigest()             // Verify digest signature
```

**Hashing:**

```
src/libxrpl/protocol/digest.cpp
  → sha512Half()               // SHA-512-Half hash
  → sha512Half_s()             // Secure variant

include/xrpl/protocol/digest.h
  → Hash function interfaces
```

**Random numbers:**

```
src/libxrpl/crypto/csprng.cpp
  → crypto_prng()              // Get CSPRNG instance
  → csprng_engine::operator()  // Generate random bytes
```

**Address encoding:**

```
src/libxrpl/protocol/tokens.cpp
  → encodeBase58Token()        // Encode to Base58Check
  → decodeBase58Token()        // Decode from Base58Check
```

**Transaction signing:**

```
src/libxrpl/protocol/STTx.cpp
  → STTx::sign()               // Sign transaction
  → STTx::checkSign()          // Verify transaction signature
```

**Peer handshake:**

```
src/xrpld/overlay/detail/Handshake.cpp
  → makeSharedValue()          // Derive session value
  → buildHandshake()           // Create handshake headers
  → verifyHandshake()          // Verify peer handshake
```

### Navigation by Task

#### Task: Understanding Ed25519 Signing

1. Start at `src/libxrpl/protocol/SecretKey.cpp:sign()`
2. Find Ed25519 case in switch statement
3. See call to `ed25519_sign()`
4. Note: External library (ed25519-donna)
5. Implementation in `src/ed25519-donna/`

#### Task: Understanding Secp256k1 Verification

1. Start at `src/libxrpl/protocol/PublicKey.cpp:verify()`
2. Find secp256k1 case
3. Follow to `verifyDigest()`
4. See canonicality check: `ecdsaCanonicality()`
5. See secp256k1 library calls: `secp256k1_ecdsa_verify()`
6. Implementation in `src/secp256k1/`

#### Task: Understanding Address Generation

1. Start at `src/libxrpl/protocol/AccountID.cpp:calcAccountID()`
2. See RIPESHA hash: `ripesha_hasher`
3. Implementation in `src/libxrpl/protocol/digest.cpp`
4. Double hash: SHA-256 then RIPEMD-160
5. Encoding: `src/libxrpl/protocol/tokens.cpp:encodeBase58Token()`

### Header vs Implementation

#### When to read headers:

```
// Headers show:
// - Function declarations
// - Class interfaces
// - Documentation comments
// - Public API

// Good for:
// - Understanding what's available
// - API reference
// - Quick lookup
```

#### When to read implementation:

```
// Implementation shows:
// - Actual algorithms
// - Error handling
// - Edge cases
// - Performance optimizations

// Good for:
// - Understanding how it works
// - Debugging
// - Learning
// - Contributing
```

### Search Patterns

#### Using grep to find code:

```
# Find all signing functions
grep -r "Buffer sign" src/libxrpl/protocol/

# Find CSPRNG usage
grep -r "crypto_prng()" src/

# Find signature verification
grep -r "verify.*signature" src/

# Find Base58 encoding
grep -r "encodeBase58" src/

# Find hash function usage
grep -r "sha512Half" src/
```

#### Using git blame:

```
# See who wrote/modified code and why
git blame src/libxrpl/protocol/SecretKey.cpp

# See commit that introduced a function
git log -S "randomSecretKey" --source --all
```

#### Using tags/symbols:

```
# Generate ctags for symbol navigation
ctags -R src/ include/

# Jump to definition in vim
# Position cursor on function name, press Ctrl-]
```

### Common Code Patterns

#### RAII Pattern:

```
// Look for:
class SomeKey {
    ~SomeKey() {
        secure_erase(/* ... */);
    }
};
```

#### Error Handling Pattern:

```
// Look for:
if (operation_failed()) {
    Throw<std::runtime_error>("Operation failed");
}
```

#### Key Type Detection Pattern:

```
// Look for:
switch (publicKeyType(pk)) {
    case KeyType::secp256k1:
        // ...
    case KeyType::ed25519:
        // ...
}
```

### Quick Reference

#### File → Purpose Mapping

| File            | Purpose                 | Key Functions                       |
| --------------- | ----------------------- | ----------------------------------- |
| `SecretKey.cpp` | Key management, signing | `randomSecretKey()`, `sign()`       |
| `PublicKey.cpp` | Verification            | `verify()`, `ecdsaCanonicality()`   |
| `digest.cpp`    | Hashing                 | `sha512Half()`, RIPESHA             |
| `csprng.cpp`    | Random generation       | `crypto_prng()`                     |
| `tokens.cpp`    | Base58 encoding         | `encodeBase58Token()`               |
| `Handshake.cpp` | Peer authentication     | `makeSharedValue()`                 |
| `STTx.cpp`      | Transaction signing     | `STTx::sign()`, `STTx::checkSign()` |

### Tips for Code Reading

1. **Start with tests**: Look in `src/test/` for usage examples
2. **Follow the data**: Track how data flows through functions
3. **Read comments**: rippled has good documentation in code
4. **Use a debugger**: Step through code to understand flow
5. **Check git history**: See why code was written that way
6. **Ask questions**: rippled has active developer community


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xrpl-commons.org/core-dev-bootcamp/module04/appendices/codebase-navigation-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.