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

Task: Understanding Ed25519 Signing

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

Task: Understanding Secp256k1 Verification

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

Task: Understanding Address Generation

Start at src/libxrpl/protocol/AccountID.cpp:calcAccountID()
See RIPESHA hash: ripesha_hasher
Implementation in src/libxrpl/protocol/digest.cpp
Double hash: SHA-256 then RIPEMD-160
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

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

PreviousAppendices NextAppendix : Debugging & Development Tools

Last updated 7 days ago

Introduction

Directory Structure

Core Cryptographic Files

1. SecretKey.cpp (404 lines)

2. PublicKey.cpp (328 lines)

3. digest.cpp (109 lines)

4. csprng.cpp (110 lines)

5. tokens.cpp

Finding Specific Functionality

"Where is...?"

Navigation by Task

Task: Understanding Ed25519 Signing

Task: Understanding Secp256k1 Verification

Task: Understanding Address Generation

Header vs Implementation

When to read headers:

When to read implementation:

Search Patterns

Using grep to find code:

Using git blame:

Using tags/symbols:

Common Code Patterns

RAII Pattern:

Error Handling Pattern:

Key Type Detection Pattern:

Quick Reference

File → Purpose Mapping

Tips for Code Reading