Skip to content

Commit d206aef

Browse files
solidsnakedevsolidsnakedev
authored
Merge pull request #55 from IntersectMBO/docs/update-address-2
docs: polish address section
2 parents a7966a6 + c6e1774 commit d206aef

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+1588
-1846
lines changed

‎docs/content/docs/addresses/address-types/base.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Base Addresses
3+
description: Standard Cardano addresses with payment and staking credentials
4+
---
5+
6+
# Base Addresses
7+
8+
Base addresses contain both a payment credential and a staking credential. This is the standard address format on Cardano.
9+
10+
## Structure
11+
12+
```
13+
Base Address = Payment Credential + Staking Credential
14+
```
15+
16+
**Payment Credential**: Controls who can spend UTXOs at this address
17+
**Staking Credential**: Controls delegation and receives staking rewards
18+
19+
Both credentials are typically derived from the same wallet, but can come from different sources (see [Franken Addresses](/docs/addresses/franken)).
20+
21+
## Construction
22+
23+
Create base addresses by instantiating the `BaseAddress` class:
24+
25+
```typescript twoslash
26+
import { Core } from "@evolution-sdk/evolution";
27+
28+
const address = new Core.BaseAddress.BaseAddress({
29+
networkId: 1, // mainnet
30+
paymentCredential: new Core.KeyHash.KeyHash({
31+
hash: new Uint8Array(28)
32+
}),
33+
stakeCredential: new Core.KeyHash.KeyHash({
34+
hash: new Uint8Array(28)
35+
})
36+
});
37+
38+
// Convert to Bech32 string
39+
const bech32 = Core.Address.toBech32(address);
40+
console.log(bech32); // "addr1..."
41+
```
42+
43+
## Parsing Addresses
44+
45+
Parse a Bech32 address string into a `BaseAddress` instance:
46+
47+
```typescript twoslash
48+
import { Core } from "@evolution-sdk/evolution";
49+
50+
const bech32 = "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd";
51+
52+
const address = Core.Address.fromBech32(bech32) as Core.BaseAddress.BaseAddress;
53+
54+
console.log("Network ID:", address.networkId);
55+
console.log("Payment:", address.paymentCredential);
56+
console.log("Stake:", address.stakeCredential);
57+
```
58+
59+
## Script-Based Addresses
60+
61+
Base addresses can use script hashes for payment and/or staking credentials:
62+
63+
```typescript twoslash
64+
import { Core } from "@evolution-sdk/evolution";
65+
66+
// Address with script credentials
67+
const scriptAddress = new Core.BaseAddress.BaseAddress({
68+
networkId: 1, // mainnet
69+
paymentCredential: new Core.ScriptHash.ScriptHash({
70+
hash: new Uint8Array(28) // 28-byte payment script hash
71+
}),
72+
stakeCredential: new Core.ScriptHash.ScriptHash({
73+
hash: new Uint8Array(28) // 28-byte stake script hash
74+
})
75+
});
76+
77+
const bech32 = Core.Address.toBech32(scriptAddress);
78+
console.log("Script-based address:", bech32);
79+
```
80+
81+
## Address Components
82+
83+
### Payment Credential
84+
- **Purpose**: Spending authorization
85+
- **Type**: Key hash (28 bytes) or script hash (28 bytes)
86+
- **Usage**: Required to sign spending transactions
87+
88+
### Staking Credential
89+
- **Purpose**: Delegation and rewards
90+
- **Type**: Key hash (28 bytes) or script hash (28 bytes)
91+
- **Usage**: Required to delegate stake or withdraw rewards
92+
93+
## Format Details
94+
95+
**Bech32 Prefix**: `addr` (mainnet) or `addr_test` (testnet)
96+
**Size**: 57 bytes on-chain
97+
98+
## Related
99+
100+
- **[Enterprise Addresses](./enterprise)** - Payment credential only
101+
- **[Reward Addresses](./reward)** - Staking credential only
102+
- **[Franken Addresses](/docs/addresses/franken)** - Addresses with credentials from different sources

‎docs/content/docs/addresses/address-types/enterprise.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: Enterprise Addresses
3+
description: Payment-only addresses without staking capability
4+
---
5+
6+
# Enterprise Addresses
7+
8+
Enterprise addresses contain only a payment credential, with no staking component.
9+
10+
## Structure
11+
12+
```
13+
Enterprise Address = Payment Credential Only
14+
```
15+
16+
**Payment Credential**: Controls who can spend UTXOs at this address
17+
**No Staking**: Cannot delegate stake or earn staking rewards
18+
19+
## Construction
20+
21+
Create enterprise addresses by instantiating the `EnterpriseAddress` class:
22+
23+
```typescript twoslash
24+
import { Core } from "@evolution-sdk/evolution";
25+
26+
const address = new Core.EnterpriseAddress.EnterpriseAddress({
27+
networkId: 1, // mainnet
28+
paymentCredential: new Core.KeyHash.KeyHash({
29+
hash: new Uint8Array(28)
30+
})
31+
});
32+
33+
// Convert to Bech32 string
34+
const bech32 = Core.Address.toBech32(address);
35+
console.log(bech32); // "addr1..."
36+
```
37+
38+
## Parsing Addresses
39+
40+
Parse a Bech32 address string into an `EnterpriseAddress` instance:
41+
42+
```typescript twoslash
43+
import { Core } from "@evolution-sdk/evolution";
44+
45+
const bech32 = "addr1vx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz6cevnrgl";
46+
47+
const address = Core.Address.fromBech32(bech32) as Core.EnterpriseAddress.EnterpriseAddress;
48+
49+
console.log("Network ID:", address.networkId);
50+
console.log("Payment:", address.paymentCredential);
51+
```
52+
53+
## Script-Based Example
54+
55+
Enterprise addresses can use script hashes as payment credentials:
56+
57+
```typescript twoslash
58+
import { Core } from "@evolution-sdk/evolution";
59+
60+
// Script address example
61+
const scriptAddr = new Core.EnterpriseAddress.EnterpriseAddress({
62+
networkId: 1, // mainnet
63+
paymentCredential: new Core.ScriptHash.ScriptHash({
64+
hash: new Uint8Array(28) // 28-byte script hash
65+
})
66+
});
67+
68+
// Convert to Bech32 string
69+
const bech32 = Core.Address.toBech32(scriptAddr);
70+
console.log("Script enterprise address:", bech32);
71+
```
72+
73+
## Format Details
74+
75+
**Bech32 Prefix**: `addr` (mainnet) or `addr_test` (testnet)
76+
**Length**: 29 bytes raw / ~59 characters Bech32
77+
**Header Bits**: `0110xxxx` (enterprise address type)
78+
**Size Advantage**: Half the size of base addresses (29 vs 57 bytes)
79+
80+
## Comparison with Base Addresses
81+
82+
| Feature | Enterprise | Base |
83+
|---------|-----------|------|
84+
| Payment credential | • Yes | • Yes |
85+
| Staking credential | ✗ No | • Yes |
86+
| Can receive funds | • Yes | • Yes |
87+
| Can delegate stake | ✗ No | • Yes |
88+
| Earns staking rewards | ✗ No | • Yes |
89+
| Size | 29 bytes | 57 bytes |
90+
| Use case | Exchanges, scripts | User wallets |
91+
92+
## Characteristics
93+
94+
**Smaller Size**: 29 bytes compared to 57 bytes for base addresses.
95+
96+
**Single Credential**: Only payment credential required - no stake key management.
97+
98+
**No Staking**: Cannot delegate stake or earn staking rewards.
99+
100+
## Related
101+
102+
- **[Base Addresses](./base)** - Addresses with both payment and staking credentials
103+
- **[Reward Addresses](./reward)** - Staking credential only

‎docs/content/docs/addresses/address-types/index.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Address Types
3+
description: Comprehensive guide to all Cardano address types and formats
4+
---
5+
6+
# Address Types
7+
8+
The Evolution SDK implements all Cardano address formats as defined in the ledger specification. This section documents the serialization and deserialization of each address type.
9+
10+
## SDK Architecture
11+
12+
Evolution SDK provides two interfaces for working with addresses:
13+
14+
**Core Address Module (`Core.Address`)**: A unified API for common address operations.
15+
- Handles `Payment Credential + Optional Staking Credential`
16+
- Automatically serializes as Base Address (with staking) or Enterprise Address (without staking)
17+
- Simplifies most serialization tasks
18+
19+
**Type-Specific Modules**: Complete implementations for protocol compliance.
20+
- `Core.BaseAddress`, `Core.EnterpriseAddress`, `Core.RewardAddress`, `Core.PointerAddress`, `Core.ByronAddress`
21+
- Required for exact CBOR encoding/decoding
22+
- Used for protocol-level operations and blockchain tooling
23+
24+
## Address Format Specifications
25+
26+
Each address type encodes different credential combinations:
27+
28+
- **Payment Credential**: Hash of payment verification key or script
29+
- **Staking Credential**: Hash of stake verification key or script
30+
31+
### Format Comparison
32+
33+
| Address Type | Payment | Staking | On-Chain Size | Bech32 Prefix | Header Bits |
34+
|--------------|---------|---------|---------------|---------------|-------------|
35+
| **[Base](./base)** | ✓ | ✓ | 57 bytes | `addr`/`addr_test` | `0000xxxx` |
36+
| **[Enterprise](./enterprise)** | ✓ | ✗ | 29 bytes | `addr`/`addr_test` | `0110xxxx` |
37+
| **[Reward](./reward)** | ✗ | ✓ | 29 bytes | `stake`/`stake_test` | `1110xxxx` |
38+
| **[Pointer](./pointer)** | ✓ | Pointer | Variable | `addr`/`addr_test` | `0100xxxx` |
39+
40+
## Address Type Documentation
41+
42+
Detailed serialization specifications for each format:
43+
44+
- **[Base Addresses](./base)** - Payment and staking credential encoding
45+
- **[Enterprise Addresses](./enterprise)** - Payment credential only encoding
46+
- **[Reward Addresses](./reward)** - Staking credential only encoding
47+
- **[Pointer Addresses](./pointer)** - On-chain stake registration reference encoding
48+
49+
## Related
50+
51+
- **[Conversion](/docs/addresses/conversion)** - Format transformations (Bech32, hex, bytes)
52+
- **[Validation](/docs/addresses/validation)** - Parsing and validation

‎docs/content/docs/addresses/address-types/meta.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"title": "Address Types",
3+
"pages": [
4+
"index",
5+
"base",
6+
"enterprise",
7+
"reward",
8+
"pointer"
9+
]
10+
}

‎docs/content/docs/addresses/address-types/pointer.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Pointer Addresses
3+
description: Payment addresses with on-chain stake pointer reference
4+
---
5+
6+
# Pointer Addresses
7+
8+
> **! Legacy Format**: Pointer addresses are rarely used in practice. This documentation exists for parsing historical transactions and understanding the complete address specification.
9+
10+
Pointer addresses contain a payment credential plus a pointer to an on-chain stake registration certificate. They reference stake information indirectly via blockchain coordinates instead of embedding a stake credential.
11+
12+
## Historical Context
13+
14+
Pointer addresses were part of the original Shelley address design, intended to optimize for size by referencing stake information rather than embedding it.
15+
16+
**Original Goal**: Save 28 bytes per address by using a pointer instead of a full stake credential.
17+
18+
**Reality**: Minimal savings, added complexity. On-chain stake registrations must be permanent and indexed. Wallet software needs additional logic to resolve pointers.
19+
20+
**Outcome**: The ecosystem converged on base addresses as the standard format.
21+
22+
## Structure
23+
24+
```
25+
Pointer Address = Payment Credential + Pointer (slot, txIndex, certIndex)
26+
```
27+
28+
**Payment Credential**: Controls who can spend UTXOs
29+
**Pointer**: References stake registration cert location on-chain
30+
31+
## Comparison with Base Addresses
32+
33+
| Feature | Pointer | Base |
34+
|---------|---------|------|
35+
| Payment credential | • Yes | • Yes |
36+
| Stake credential | Via pointer | Direct embed |
37+
| Size | Variable | Fixed 57 bytes |
38+
| Complexity | High | Low |
39+
| Adoption | Rare | Universal |
40+
| Recommended | ✗ No | • Yes |
41+
42+
## Parsing Pointer Addresses
43+
44+
If you encounter a pointer address, you can parse it using the `AddressDetails` utility:
45+
46+
```typescript twoslash
47+
import { AddressDetails } from "@evolution-sdk/evolution";
48+
49+
// Parse a pointer address from Bech32
50+
const details = AddressDetails.fromBech32("addr_test1gz...");
51+
52+
if (details.type === "PointerAddress" && details.address._tag === "PointerAddress") {
53+
// Type narrowed to PointerAddress - now we can access pointer-specific properties
54+
console.log("Payment credential:", details.address.paymentCredential);
55+
console.log("Pointer:", details.address.pointer);
56+
}
57+
```
58+
59+
## Migration to Base Address
60+
61+
If you have funds at a pointer address, you can send them to a base address using your wallet. Create a transaction that spends from the pointer address UTXOs and sends to your base address. This requires the appropriate signing keys for the payment credential referenced in the pointer address.
62+
63+
## Advanced: Understanding Pointer Structure
64+
65+
The pointer identifies where the stake registration certificate lives on-chain:
66+
67+
- **slot**: Block slot number containing the registration
68+
- **txIndex**: Transaction position within that block
69+
- **certIndex**: Certificate position within that transaction
70+
71+
This triplet uniquely identifies the stake registration certificate.
72+
73+
### Stake Registration Requirement
74+
75+
For a pointer address to work:
76+
77+
1. A stake registration certificate must exist on-chain at the pointer location
78+
2. That certificate must register a stake credential
79+
3. The pointer (slot, txIndex, certIndex) must be valid and resolvable
80+
81+
If any of these fail, the address is invalid.
82+
83+
## Advanced: Manual Construction
84+
85+
This example shows the structure for completeness. **Do not use in production**:
86+
87+
```typescript twoslash
88+
import { Core } from "@evolution-sdk/evolution";
89+
90+
// Create payment credential (key hash)
91+
const paymentCred = new Core.KeyHash.KeyHash({
92+
hash: new Uint8Array(28).fill(0)
93+
});
94+
95+
// Create pointer to stake registration certificate
96+
// Note: Pointer uses numbers, not bigint
97+
const pointer = new Core.Pointer.Pointer({
98+
slot: 12345,
99+
txIndex: 2,
100+
certIndex: 0
101+
});
102+
103+
// Construct pointer address (rarely used in practice)
104+
// PointerAddress is a separate class from regular Address
105+
const pointerAddr = new Core.PointerAddress.PointerAddress({
106+
networkId: 0,
107+
paymentCredential: paymentCred,
108+
pointer: pointer
109+
});
110+
111+
console.log("Pointer address (deprecated):", pointerAddr);
112+
```
113+
114+
## Format Details
115+
116+
**Bech32 Prefix**: `addr` (mainnet) or `addr_test` (testnet)
117+
**Length**: Variable (34-48 bytes depending on pointer values)
118+
**Header Bits**: `0100xxxx` (pointer address type)
119+
120+
## Related
121+
122+
- **[Base Addresses](./base)** - Standard address format with embedded stake credential
123+
- **[Enterprise Addresses](./enterprise)** - Payment credential only

0 commit comments

Comments
 (0)