|
| 1 | +--- |
| 2 | +title: Address |
| 3 | +description: Working with Cardano addresses using Core.Address |
| 4 | +--- |
| 5 | + |
| 6 | +# Address |
| 7 | + |
| 8 | +The Evolution SDK provides `Core.Address` for working with modern Cardano addresses. This module handles parsing, validation, inspection, and conversion between formats. |
| 9 | + |
| 10 | +## Modern Address Types |
| 11 | + |
| 12 | +Cardano primarily uses two address types today: |
| 13 | + |
| 14 | +- **Base Address** - Payment + staking credentials (most common) |
| 15 | +- **Enterprise Address** - Payment credential only (no staking rewards) |
| 16 | + |
| 17 | +Legacy formats (Byron, Pointer) exist for historical compatibility but are no longer used in practice. |
| 18 | + |
| 19 | +## Basic Operations |
| 20 | + |
| 21 | +### Parsing Addresses |
| 22 | + |
| 23 | +```typescript twoslash |
| 24 | +import { Core } from "@evolution-sdk/evolution"; |
| 25 | + |
| 26 | +// Parse from Bech32 (most common format) |
| 27 | +const address = Core.Address.fromBech32( |
| 28 | + "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd" |
| 29 | +); |
| 30 | + |
| 31 | +// Parse from hex |
| 32 | +const address2 = Core.Address.fromHex( |
| 33 | + "01195a6a8c607b8a0237109aab5e31b7c8828509fb17e4019cd381021a4f8a081b7bd1b0d35972c0e8eaba8e5c923c99d66a3bbe78ff23c5855" |
| 34 | +); |
| 35 | +``` |
| 36 | + |
| 37 | +### Converting Formats |
| 38 | + |
| 39 | +```typescript twoslash |
| 40 | +import { Core } from "@evolution-sdk/evolution"; |
| 41 | + |
| 42 | +const address = Core.Address.fromBech32( |
| 43 | + "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd" |
| 44 | +); |
| 45 | + |
| 46 | +// Convert to different formats |
| 47 | +const bech32 = Core.Address.toBech32(address); // "addr1qx2k..." |
| 48 | +const hex = Core.Address.toHex(address); // "01195a6a..." |
| 49 | +const bytes = Core.Address.toBytes(address); // Uint8Array |
| 50 | +``` |
| 51 | + |
| 52 | +### Validating User Input |
| 53 | + |
| 54 | +```typescript twoslash |
| 55 | +import { Core } from "@evolution-sdk/evolution"; |
| 56 | + |
| 57 | +function validateAddress(input: string): Core.Address.Address | null { |
| 58 | + try { |
| 59 | + const address = Core.Address.fromBech32(input); |
| 60 | + |
| 61 | + // Check network (0 = testnet, 1 = mainnet) |
| 62 | + if (address.networkId !== 1) { |
| 63 | + console.warn("Not a mainnet address"); |
| 64 | + } |
| 65 | + |
| 66 | + return address; |
| 67 | + } catch (error) { |
| 68 | + console.error("Invalid address:", error); |
| 69 | + return null; |
| 70 | + } |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +## Address Inspection |
| 75 | + |
| 76 | +### Type Checking |
| 77 | + |
| 78 | +```typescript twoslash |
| 79 | +import { Core } from "@evolution-sdk/evolution"; |
| 80 | + |
| 81 | +const address = Core.Address.fromBech32( |
| 82 | + "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd" |
| 83 | +); |
| 84 | + |
| 85 | +// Check address type |
| 86 | +const details = Core.Address.getAddressDetails(Core.Address.toBech32(address)); |
| 87 | +const isEnterprise = Core.Address.isEnterprise(address); // false |
| 88 | +const hasStaking = Core.Address.hasStakingCredential(address); // true |
| 89 | + |
| 90 | +if (details?.type === "Base") { |
| 91 | + console.log("Base address with staking capability"); |
| 92 | +} else if (isEnterprise) { |
| 93 | + console.log("Enterprise address - no staking rewards"); |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +### Address Details |
| 98 | + |
| 99 | +For comprehensive information about an address: |
| 100 | + |
| 101 | +```typescript twoslash |
| 102 | +import { Core } from "@evolution-sdk/evolution"; |
| 103 | + |
| 104 | +const details = Core.Address.getAddressDetails( |
| 105 | + "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd" |
| 106 | +); |
| 107 | + |
| 108 | +if (details) { |
| 109 | + console.log("Type:", details.type); // "Base" |
| 110 | + console.log("Network:", details.networkId); // 1 (mainnet) |
| 111 | + console.log("Bech32:", details.address.bech32); // Original Bech32 string |
| 112 | + console.log("Hex:", details.address.hex); // Hex representation |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +## Address Construction |
| 117 | + |
| 118 | +For advanced use cases, you can construct addresses from credentials: |
| 119 | + |
| 120 | +```typescript twoslash |
| 121 | +import { Core } from "@evolution-sdk/evolution"; |
| 122 | + |
| 123 | +// Create payment credential from key hash |
| 124 | +const paymentCred = new Core.KeyHash.KeyHash({ |
| 125 | + hash: new Uint8Array(28) // 28-byte key hash |
| 126 | +}); |
| 127 | + |
| 128 | +// Create staking credential |
| 129 | +const stakeCred = new Core.KeyHash.KeyHash({ |
| 130 | + hash: new Uint8Array(28) // 28-byte key hash |
| 131 | +}); |
| 132 | + |
| 133 | +// Construct base address directly |
| 134 | +const address = new Core.Address.Address({ |
| 135 | + networkId: 1, // mainnet |
| 136 | + paymentCredential: paymentCred, |
| 137 | + stakingCredential: stakeCred |
| 138 | +}); |
| 139 | + |
| 140 | +const bech32 = Core.Address.toBech32(address); |
| 141 | +``` |
| 142 | + |
| 143 | +## Legacy Address Types |
| 144 | + |
| 145 | +For historical compatibility, Evolution SDK supports legacy address formats via `Core.AddressEras`: |
| 146 | + |
| 147 | +- **Byron addresses** - Legacy Byron-era format (no longer used) |
| 148 | +- **Pointer addresses** - Reference stake credentials via on-chain pointers (deprecated) |
| 149 | + |
| 150 | +These are automatically handled when parsing existing UTXOs but should not be used for new addresses. |
| 151 | + |
| 152 | +## Summary |
| 153 | + |
| 154 | +| Function | Purpose | |
| 155 | +|----------|---------| |
| 156 | +| `fromBech32()` | Parse Bech32 address string | |
| 157 | +| `fromHex()` | Parse hex address string | |
| 158 | +| `toBech32()` | Convert to Bech32 string | |
| 159 | +| `toHex()` | Convert to hex string | |
| 160 | +| `isEnterprise()` | Check if enterprise address (no staking) | |
| 161 | +| `hasStakingCredential()` | Check if address has staking capability | |
| 162 | +| `getAddressDetails()` | Get comprehensive address information | |
| 163 | + |
| 164 | +## Best Practices |
| 165 | + |
| 166 | +1. **Use Base addresses** for most applications (enables staking rewards) |
| 167 | +2. **Validate network ID** to prevent testnet/mainnet mixups |
| 168 | +3. **Parse once, reuse** - avoid re-parsing the same address strings |
| 169 | +4. **Handle errors gracefully** when parsing user input |
| 170 | + |
| 171 | +## Next Steps |
| 172 | + |
| 173 | +- [Address Validation](/docs/addresses/validation) - Error handling and validation patterns |
| 174 | +- [Address Conversion](/docs/addresses/conversion) - Transform between formats |
| 175 | +- [Address Construction](/docs/addresses/construction) - Build addresses from credentials |
0 commit comments