Address Overview

Cardano addresses identify where funds can be sent and who controls them. The Evolution SDK provides Core.Address for working with payment credentials and optional staking credentials, handling the complexity of different address formats.

The Core Address Model

Instead of dealing with multiple address types (BaseAddress, EnterpriseAddress, etc.), Evolution SDK uses a unified Core.Address structure:

Address = Payment Credential + Optional Staking Credential

This simple model covers the most common use cases:

• With staking credential → Functions like a Base Address (supports delegation)
• Without staking credential → Functions like an Enterprise Address (payment only)

Getting Started

You can import address functionality in two ways:

Option 1: From the Main Package (Recommended)

import { Core } from "@evolution-sdk/evolution";

// Example: Create an address with both payment and stake credentials
const paymentCred = new Core.KeyHash.KeyHash({ hash: new Uint8Array(28) });
const address = new Core.Address.Address({
  networkId: 1,
  paymentCredential: paymentCred
});

Note: The double naming (e.g., Core.Address.Address) is intentional - the first is the module namespace, the second is the class constructor.

Option 2: Direct Module Imports

import { Address } from "@evolution-sdk/evolution/core/Address";
import { KeyHash } from "@evolution-sdk/evolution/core/KeyHash";

// Same functionality, imported directly from modules
const paymentCred = new KeyHash({ hash: new Uint8Array(28) });
const address = new Address({
  networkId: 1,
  paymentCredential: paymentCred
});

Quick Start

Parse and Inspect Addresses

import { Core } from "@evolution-sdk/evolution"

const bech32 = "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd"

// Parse from Bech32
const address = Core.Address.fromBech32(bech32)

// Inspect properties
console.log("Network:", address.networkId === 1 ? "mainnet" : "testnet")
console.log("Payment credential:", address.paymentCredential)
console.log("Staking credential:", address.stakingCredential)

// Check if it has staking capability
const hasStaking = address.stakingCredential !== undefined
console.log("Supports staking:", hasStaking)

Create New Addresses

import { Core } from "@evolution-sdk/evolution"

// Example credentials (in real code, derive from keys)
const paymentCred = new Core.KeyHash.KeyHash({ 
  hash: new Uint8Array(28) // Your payment key hash
})
const stakeCred = new Core.KeyHash.KeyHash({ 
  hash: new Uint8Array(28) // Your stake key hash
})

// Address with staking (like Base Address)
const stakingAddress = new Core.Address.Address({
  networkId: 1, // mainnet
  paymentCredential: paymentCred,
  stakingCredential: stakeCred
})

// Address without staking (like Enterprise Address)
const paymentOnlyAddress = new Core.Address.Address({
  networkId: 1,
  paymentCredential: paymentCred
  // No stakingCredential = enterprise-like behavior
})

// Convert to Bech32 string
const bech32String = Core.Address.toBech32(stakingAddress)

Learn about the Core.Address module →

When to Use Each Pattern

Address with Staking Credential

Use when:

• • Building standard user wallets
• • You want staking rewards
• • General purpose applications
• • Maximum feature compatibility

Equivalent to: Base Address in Cardano specification

import { Core } from "@evolution-sdk/evolution";

const paymentCred = new Core.KeyHash.KeyHash({ hash: new Uint8Array(28) });
const stakeCred = new Core.KeyHash.KeyHash({ hash: new Uint8Array(28) });

const address = new Core.Address.Address({
  networkId: 1,
  paymentCredential: paymentCred,
  stakingCredential: stakeCred // ← Enables staking
})

Address without Staking Credential

Use when:

• • Running an exchange (custodial platform)
• • Smart contract addresses
• • Don't need staking capability
• • Want simpler structure

Equivalent to: Enterprise Address in Cardano specification

import { Core } from "@evolution-sdk/evolution";

const paymentCred = new Core.KeyHash.KeyHash({ hash: new Uint8Array(28) });

const address = new Core.Address.Address({
  networkId: 1,
  paymentCredential: paymentCred
  // No stakingCredential = payment only
})

Address Anatomy

With Staking (Standard Pattern)

┌─────────────────────────────────────────────────────┐
│            Address (with staking)                    │
├────────────────────────┬────────────────────────────┤
│  Payment Credential    │  Staking Credential        │
│  (28 bytes)            │  (28 bytes)                │
│  Controls spending     │  Controls delegation       │
└────────────────────────┴────────────────────────────┘
         ↓                         ↓
    Spend UTXOs            Delegate & earn rewards

Without Staking (Basic Pattern)

┌──────────────────────────┐
│  Address (payment only)  │
├──────────────────────────┤
│  Payment Credential      │
│  (28 bytes)              │
│  Controls spending       │
└──────────────────────────┘
         ↓
    Spend UTXOs
    (no staking)

Network Prefixes

Addresses use different Bech32 prefixes based on network:

Note: The Evolution SDK automatically handles the correct prefix based on the networkId you provide (1 = mainnet, 0 = testnet).

Understanding Address Eras

While Core.Address covers most use cases, Cardano's ledger specification defines several specific address types. These are called Address Eras:

For most applications, you don't need to think about these era-specific types. The Address class handles them automatically.

For advanced use cases requiring era-specific features, see the Address Types guide →

Note: "Franken addresses" are not a separate era - they're just Base addresses constructed with independent payment and stake credentials. See Franken Addresses for this advanced pattern.

Key Concepts

Payment Credential

Controls spending of funds:

• Required to sign spending transactions
• Can be key hash (28 bytes) or script hash (28 bytes)
• Loss of payment key = loss of funds

Staking Credential

Controls delegation and rewards:

• Required to delegate stake
• Required to withdraw rewards
• Can be key hash (28 bytes) or script hash (28 bytes)
• Independent from payment credential

Credential Types

Both payment and staking credentials can be:

Key Hash: Derived from a cryptographic key (user-controlled)
Script Hash: Derived from a Plutus script (smart contract-controlled)

Common Operations

Conversion

Convert between formats (Bech32, hex, bytes):

Address Conversion Guide →

Validation

Verify address format and network:

Address Validation Guide →

Next Steps

Core Concepts:

• Core.Address - How to parse, validate, and convert addresses
• Address Types - Comprehensive coverage of all address types

Advanced Patterns:

• Franken Addresses - Constructing addresses with split credential ownership

Practical Guides:

• Conversion - Transform between Bech32, hex, and bytes
• Validation - Verify addresses before use

Related Topics:

• Transactions - Sending funds to addresses
• Staking - Delegation and rewards
• Wallets - Key management and address derivation