0
# Core Cryptographic Operations
1

2
Low-level cryptographic functions, address encoding/decoding, binary transaction encoding, and fundamental XRPL constants that form the foundation of XRPL interactions.
3

4
## Capabilities
5

6
### Cryptographic Key Operations
7

8
Generate seeds, derive keypairs, and perform cryptographic signing operations using Ed25519 or secp256k1 algorithms.
9

10
```python { .api }
11
from xrpl.core.keypairs import (
12
    generate_seed, derive_keypair, derive_classic_address, 
13
    sign, is_valid_message
14
)
15

16
def generate_seed(
17
    algorithm: CryptoAlgorithm = CryptoAlgorithm.ED25519, 
18
    entropy: bytes = None
19
) -> str:
20
    """
21
    Generate a cryptographic seed for creating keypairs.
22
    
23
    Args:
24
        algorithm: Cryptographic algorithm to use
25
        entropy: Optional entropy bytes for seed generation
26
        
27
    Returns:
28
        Base58-encoded seed string
29
    """
30

31
def derive_keypair(seed: str, algorithm: CryptoAlgorithm = None) -> tuple[str, str]:
32
    """
33
    Derive a public/private keypair from a seed.
34
    
35
    Args:
36
        seed: Base58-encoded seed string
37
        algorithm: Cryptographic algorithm (inferred from seed if not provided)
38
        
39
    Returns:
40
        Tuple of (public_key_hex, private_key_hex)
41
    """
42

43
def derive_classic_address(public_key: str) -> str:
44
    """
45
    Derive XRPL classic address from public key.
46
    
47
    Args:
48
        public_key: Hex-encoded public key
49
        
50
    Returns:
51
        Classic address string
52
    """
53

54
def sign(message: bytes, private_key: str) -> str:
55
    """
56
    Sign a message with a private key.
57
    
58
    Args:
59
        message: Message bytes to sign
60
        private_key: Hex-encoded private key
61
        
62
    Returns:
63
        Hex-encoded signature
64
    """
65

66
def is_valid_message(message: bytes, signature: str, public_key: str) -> bool:
67
    """
68
    Verify a message signature.
69
    
70
    Args:
71
        message: Original message bytes
72
        signature: Hex-encoded signature
73
        public_key: Hex-encoded public key
74
        
75
    Returns:
76
        True if signature is valid
77
    """
78
```
79

80
### Address Encoding and Decoding
81

82
Convert between different XRPL address formats and encode/decode various XRPL identifiers.
83

84
```python { .api }
85
from xrpl.core.addresscodec import (
86
    encode_classic_address, decode_classic_address,
87
    classic_address_to_xaddress, xaddress_to_classic_address,
88
    is_valid_classic_address, is_valid_xaddress,
89
    ensure_classic_address,
90
    encode_seed, decode_seed,
91
    encode_account_public_key, decode_account_public_key,
92
    encode_node_public_key, decode_node_public_key
93
)
94

95
def encode_classic_address(public_key: str, tag: int = None, is_test: bool = False) -> str:
96
    """
97
    Encode a classic XRPL address from public key.
98
    
99
    Args:
100
        public_key: Hex-encoded public key
101
        tag: Optional destination tag
102
        is_test: Whether this is a test network address
103
        
104
    Returns:
105
        Classic address string
106
    """
107

108
def decode_classic_address(address: str) -> bytes:
109
    """
110
    Decode a classic address to its raw bytes.
111
    
112
    Args:
113
        address: Classic address string
114
        
115
    Returns:
116
        Address bytes
117
    """
118

119
def classic_address_to_xaddress(address: str, tag: int = None, is_test_network: bool = False) -> str:
120
    """
121
    Convert classic address to X-address format.
122
    
123
    Args:
124
        address: Classic address string
125
        tag: Optional destination tag
126
        is_test_network: Whether this is a test network
127
        
128
    Returns:
129
        X-address string
130
    """
131

132
def xaddress_to_classic_address(xaddress: str) -> tuple[str, int, bool]:
133
    """
134
    Convert X-address to classic address format.
135
    
136
    Args:
137
        xaddress: X-address string
138
        
139
    Returns:
140
        Tuple of (classic_address, tag, is_test_network)
141
    """
142

143
def is_valid_classic_address(address: str) -> bool:
144
    """Check if string is a valid classic address format."""
145

146
def is_valid_xaddress(address: str) -> bool:
147
    """Check if string is a valid X-address format."""
148

149
def ensure_classic_address(address: str) -> str:
150
    """
151
    Ensure address is in classic format, converting from X-address if needed.
152
    
153
    Args:
154
        address: Address in any valid format
155
        
156
    Returns:
157
        Classic address string
158
    """
159
```
160

161
### Binary Transaction Encoding
162

163
Encode and decode XRPL transactions to/from binary format for signing and network transmission.
164

165
```python { .api }
166
from xrpl.core.binarycodec import (
167
    encode, decode,
168
    encode_for_signing, encode_for_multisigning,
169
    encode_for_signing_batch, encode_for_signing_claim
170
)
171

172
def encode(transaction_object: dict) -> str:
173
    """
174
    Encode transaction object to binary hex format.
175
    
176
    Args:
177
        transaction_object: Transaction as dictionary
178
        
179
    Returns:
180
        Hex-encoded binary transaction
181
    """
182

183
def decode(hex_string: str) -> dict:
184
    """
185
    Decode binary transaction data to transaction object.
186
    
187
    Args:
188
        hex_string: Hex-encoded binary transaction
189
        
190
    Returns:
191
        Transaction object as dictionary
192
    """
193

194
def encode_for_signing(transaction: dict) -> str:
195
    """
196
    Encode transaction for signing (adds signing prefix).
197
    
198
    Args:
199
        transaction: Transaction object
200
        
201
    Returns:
202
        Hex-encoded transaction ready for signing
203
    """
204

205
def encode_for_multisigning(transaction: dict, signing_account: str) -> str:
206
    """
207
    Encode transaction for multisigning.
208
    
209
    Args:
210
        transaction: Transaction object
211
        signing_account: Account address doing the signing
212
        
213
    Returns:
214
        Hex-encoded transaction ready for multisigning
215
    """
216

217
def encode_for_signing_batch(transactions: list[dict]) -> list[str]:
218
    """
219
    Encode multiple transactions for batch signing.
220
    
221
    Args:
222
        transactions: List of transaction objects
223
        
224
    Returns:
225
        List of hex-encoded transactions ready for signing
226
    """
227
```
228

229
### Constants and Types
230

231
```python { .api }
232
from xrpl.constants import (
233
    SEED_LENGTH, XRPL_ALPHABET,
234
    ISO_CURRENCY_REGEX, HEX_REGEX, HEX_CURRENCY_REGEX, HEX_MPTID_REGEX,
235
    MIN_IOU_EXPONENT, MAX_IOU_EXPONENT, MAX_IOU_PRECISION,
236
    MIN_IOU_MANTISSA, MAX_IOU_MANTISSA,
237
    IOU_DECIMAL_CONTEXT, DROPS_DECIMAL_CONTEXT
238
)
239

240
# Cryptographic algorithm options
241
class CryptoAlgorithm(str, Enum):
242
    ED25519 = "ed25519"
243
    SECP256K1 = "secp256k1"
244

245
# Regex patterns for validation
246
ISO_CURRENCY_REGEX: Pattern[str]  # Matches ISO currency codes like "USD"
247
HEX_REGEX: Pattern[str]  # Matches hex strings
248
HEX_CURRENCY_REGEX: Pattern[str]  # Matches hex-encoded currencies (40 chars)
249
HEX_MPTID_REGEX: Pattern[str]  # Matches MPT IDs (48 hex chars)
250

251
# IOU amount constants
252
SEED_LENGTH: int  # Standard seed length
253
MIN_IOU_EXPONENT: int = -96
254
MAX_IOU_EXPONENT: int = 80
255
MAX_IOU_PRECISION: int = 16
256
MIN_IOU_MANTISSA: int = 10**15
257
MAX_IOU_MANTISSA: int = 10**16 - 1
258

259
# Decimal contexts for precise arithmetic
260
IOU_DECIMAL_CONTEXT: Context  # For IOU amounts
261
DROPS_DECIMAL_CONTEXT: Context  # For XRP drops
262
```
263

264
### Exceptions
265

266
```python { .api }
267
class XRPLAddressCodecException(XRPLException):
268
    """Exception for address codec operations."""
269

270
class XRPLBinaryCodecException(XRPLException):
271
    """Exception for binary codec operations."""
272

273
class XRPLKeypairsException(XRPLException):
274
    """Exception for keypair operations."""
275
```
276

277
## Usage Examples
278

279
### Creating a New Wallet from Scratch
280

281
```python
282
from xrpl.core.keypairs import generate_seed, derive_keypair, derive_classic_address
283
from xrpl import CryptoAlgorithm
284

285
# Generate a new seed
286
seed = generate_seed(CryptoAlgorithm.ED25519)
287
print(f"Seed: {seed}")
288

289
# Derive keypair from seed
290
public_key, private_key = derive_keypair(seed)
291
print(f"Public key: {public_key}")
292

293
# Derive address from public key
294
address = derive_classic_address(public_key)
295
print(f"Address: {address}")
296
```
297

298
### Address Format Conversions
299

300
```python
301
from xrpl.core.addresscodec import (
302
    classic_address_to_xaddress, xaddress_to_classic_address,
303
    is_valid_classic_address, ensure_classic_address
304
)
305

306
# Convert classic to X-address
307
classic_addr = "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
308
xaddr = classic_address_to_xaddress(classic_addr, tag=12345, is_test_network=True)
309
print(f"X-address: {xaddr}")
310

311
# Convert back to classic
312
classic_addr2, tag, is_test = xaddress_to_classic_address(xaddr)
313
print(f"Classic: {classic_addr2}, Tag: {tag}, TestNet: {is_test}")
314

315
# Validate address formats
316
print(f"Valid classic: {is_valid_classic_address(classic_addr)}")
317

318
# Ensure classic format (converts X-address if needed)
319
classic_addr3 = ensure_classic_address(xaddr)
320
print(f"Ensured classic: {classic_addr3}")
321
```
322

323
### Binary Transaction Encoding
324

325
```python
326
from xrpl.core.binarycodec import encode, decode, encode_for_signing
327
from xrpl.models.transactions import Payment
328

329
# Create a payment transaction
330
payment = Payment(
331
    account="rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
332
    destination="rLNaPoKeeBjZe2qs6x52yVPZpZ8td4dc6w",
333
    amount="1000000",
334
    sequence=1,
335
    fee="12"
336
)
337

338
# Encode to binary format
339
binary_tx = encode(payment.to_dict())
340
print(f"Binary transaction: {binary_tx}")
341

342
# Decode back to transaction object
343
decoded_tx = decode(binary_tx)
344
print(f"Decoded transaction: {decoded_tx}")
345

346
# Encode for signing (adds signing prefix)
347
signing_blob = encode_for_signing(payment.to_dict())
348
print(f"Signing blob: {signing_blob}")
349
```