Account API

The Account API provides a simple abstraction for creating and managing Cardano accounts. It encapsulates features like CIP-1852 compatible address derivation, BIP-39 mnemonic generation, key management, and transaction signing through a simple Account class.

Key Features

• Mnemonic Generation: Generate BIP-39 compatible mnemonic phrases
• Address Derivation: Derive various types of Cardano addresses (base, enterprise, stake, change)
• Key Management: Manage private keys and key pairs securely
• Transaction Signing: Sign transactions with account credentials
• Network Support: Support for mainnet, testnet, and preview networks
• DRep Support: Generate DRep keys, credentials, and CIP-129 DRep IDs for governance participation
• Committee Key Support: Manage Constitutional Committee cold and hot keys for governance

Core Classes

Account Class

The main class for account operations, providing methods for address generation, key management, and transaction signing.

Factory Methods (Recommended):

• Account.createFromMnemonic(Network, String) - Create account from mnemonic
• Account.createFromMnemonic(Network, String, int account, int index) - Create account from mnemonic at specific derivation path
• Account.createFromRootKey(Network, byte[]) - Create account from root key
• Account.createFromAccountKey(Network, byte[]) - Create account from account-level key

Constructors:

• Account(Network network) - Create new account with generated mnemonic
• Account(Network network, String mnemonic) - Create account from existing mnemonic (deprecated, use factory methods)

Address Methods:

• baseAddress() - Get base address for payments
• changeAddress() - Get change address
• enterpriseAddress() - Get enterprise address (no staking)
• stakeAddress() - Get stake address for delegation

Key Management Methods:

• hdKeyPair() - Get payment HD key pair
• stakeHdKeyPair() - Get stake HD key pair
• changeHdKeyPair() - Get change HD key pair
• privateKeyBytes() / publicKeyBytes() - Get raw key bytes
• getRootKeyPair() - Get root key pair (if available)
• mnemonic() - Get mnemonic phrase

DRep Key Methods:

• drepHdKeyPair() - Get DRep HD key pair
• drepKey() - Get DRepKey object
• drepId() - Get CIP-129 bech32 DRep ID
• legacyDRepId() - Get CIP-105 DRep ID (deprecated)
• drepCredential() - Get DRep credential

Committee Key Methods:

• committeeColdKeyPair() / committeeColdKey() / committeeColdCredential() - Constitutional Committee cold keys
• committeeHotKeyPair() / committeeHotKey() / committeeHotCredential() - Constitutional Committee hot keys

Signing Methods:

• sign(Transaction) - Sign with payment key
• signWithStakeKey(Transaction) - Sign with stake key
• signWithDRepKey(Transaction) - Sign with DRep key
• signWithCommitteeColdKey(Transaction) - Sign with Committee cold key
• signWithCommitteeHotKey(Transaction) - Sign with Committee hot key

Usage Examples

Creating Accounts

Create accounts using the recommended factory methods or constructors:

// Recommended: Factory methods
Account account = Account.createFromMnemonic(Networks.testnet(), mnemonic);

// With specific account and address index (m/1852'/1815'/1'/0/2)
Account account = Account.createFromMnemonic(Networks.testnet(), mnemonic, 1, 2);

// From root key (96 bytes: private key + chain code)
byte[] rootKeyBytes = ...;
Account account = Account.createFromRootKey(Networks.testnet(), rootKeyBytes);

// From account-level key (96 bytes)
byte[] accountKey = ...;
Account account = Account.createFromAccountKey(Networks.mainnet(), accountKey);

You can also use constructors for generating new accounts:

// Generate new account with random mnemonic
Account newAccount = new Account(Networks.testnet());
String generatedMnemonic = newAccount.mnemonic();

// Create mainnet account
Account mainnetAccount = new Account(Networks.mainnet());

Address Generation

Retrieve different types of addresses from an account:

// Get base address (payment + staking)
String baseAddress = account.baseAddress();
System.out.println("Base Address: " + baseAddress);

// Get enterprise address (payment only)
String enterpriseAddress = account.enterpriseAddress();
System.out.println("Enterprise Address: " + enterpriseAddress);

// Get stake address (for delegation)
String stakeAddress = account.stakeAddress();
System.out.println("Stake Address: " + stakeAddress);

// Get change address
String changeAddress = account.changeAddress();
System.out.println("Change Address: " + changeAddress);

Key Management

Access private keys, public keys, and credentials:

// Get private key bytes
byte[] privateKey = account.privateKeyBytes();

// Get HD key pair (payment)
HdKeyPair keyPair = account.hdKeyPair();
HdPublicKey publicKey = keyPair.getPublicKey();
HdPrivateKey privateKey = keyPair.getPrivateKey();

// Get mnemonic phrase
String mnemonic = account.mnemonic();

Stake and Change Key Pairs

// Get stake HD key pair
HdKeyPair stakeKeyPair = account.stakeHdKeyPair();

// Get change HD key pair
HdKeyPair changeKeyPair = account.changeHdKeyPair();

// Get root key pair (available when created from mnemonic or root key)
Optional<HdKeyPair> rootKeyPair = account.getRootKeyPair();

DRep Keys

Access DRep keys for governance participation:

// Get DRep HD key pair
HdKeyPair drepKeyPair = account.drepHdKeyPair();

// Get DRepKey object (provides access to signing/verification keys and bech32 formats)
DRepKey drepKey = account.drepKey();

// Get CIP-129 DRep ID (e.g. "drep1yg7a8f...")
String drepId = account.drepId();

// Get DRep credential for governance transactions
Credential drepCredential = account.drepCredential();

Committee Cold Keys

Access Constitutional Committee cold keys:

// Get Committee Cold HD key pair
HdKeyPair ccColdKeyPair = account.committeeColdKeyPair();

// Get CommitteeColdKey object
CommitteeColdKey ccColdKey = account.committeeColdKey();

// Get CIP-129 Committee Cold ID (e.g. "cc_cold1zg6ed5...")
String ccColdId = ccColdKey.id();

// Get Committee Cold credential
Credential ccColdCredential = account.committeeColdCredential();

Committee Hot Keys

Access Constitutional Committee hot keys:

// Get Committee Hot HD key pair
HdKeyPair ccHotKeyPair = account.committeeHotKeyPair();

// Get CommitteeHotKey object
CommitteeHotKey ccHotKey = account.committeeHotKey();

// Get CIP-129 Committee Hot ID (e.g. "cc_hot1qth000...")
String ccHotId = ccHotKey.id();

// Get Committee Hot credential
Credential ccHotCredential = account.committeeHotCredential();

Transaction Signing

Sign transactions using the account’s payment key:

// Sign a transaction directly with the account
Transaction signedTx = account.sign(transaction);

Governance Signing

Sign governance transactions with the appropriate key:

// Sign with stake key (e.g., stake delegation, stake registration)
Transaction signedTx = account.signWithStakeKey(transaction);

// Sign with DRep key (e.g., DRep registration, voting)
Transaction signedTx = account.signWithDRepKey(transaction);

// Sign with Committee Cold key (e.g., committee authorization)
Transaction signedTx = account.signWithCommitteeColdKey(transaction);

// Sign with Committee Hot key (e.g., committee voting)
Transaction signedTx = account.signWithCommitteeHotKey(transaction);

Governance SignerProviders

Use SignerProviders helpers for composable governance signing with QuickTxBuilder:

// Stake key signer (for stake delegation, withdrawal transactions)
QuickTxBuilder builder = new QuickTxBuilder(backendService);
Result<String> result = builder.compose(tx)
    .withSigner(SignerProviders.signerFrom(account))
    .withSigner(SignerProviders.stakeKeySignerFrom(account))
    .completeAndWait();

// DRep key signer (for DRep registration, voting transactions)
Result<String> result = builder.compose(tx)
    .withSigner(SignerProviders.signerFrom(account))
    .withSigner(SignerProviders.drepKeySignerFrom(account))
    .completeAndWait();

// Committee Cold key signer
Result<String> result = builder.compose(tx)
    .withSigner(SignerProviders.signerFrom(account))
    .withSigner(SignerProviders.committeeColdKeySignerFrom(account))
    .completeAndWait();

// Committee Hot key signer
Result<String> result = builder.compose(tx)
    .withSigner(SignerProviders.signerFrom(account))
    .withSigner(SignerProviders.committeeHotKeySignerFrom(account))
    .completeAndWait();

You can also sign with an HD key pair directly:

// Sign with DRep HD key pair
SignerProviders.signerFrom(account.drepHdKeyPair());

Advanced Usage

Multi-Account Management

Manage multiple accounts for different purposes:

// Main spending account
Account spendingAccount = Account.createFromMnemonic(Networks.mainnet(), spendingMnemonic);

// Savings account
Account savingsAccount = Account.createFromMnemonic(Networks.mainnet(), savingsMnemonic);

// Business account
Account businessAccount = Account.createFromMnemonic(Networks.mainnet(), businessMnemonic);

// Get addresses for each account
String spendingAddress = spendingAccount.baseAddress();
String savingsAddress = savingsAccount.baseAddress();
String businessAddress = businessAccount.baseAddress();

Network-Specific Operations

Handle different network configurations:

// Mainnet account
Account mainnetAccount = Account.createFromMnemonic(Networks.mainnet(), mnemonic);
String mainnetAddress = mainnetAccount.baseAddress(); // addr1...

// Testnet account
Account testnetAccount = Account.createFromMnemonic(Networks.testnet(), mnemonic);
String testnetAddress = testnetAccount.baseAddress(); // addr_test1...

Best Practices

Mnemonic Validation

// Validate mnemonic using MnemonicUtil (throws on invalid input)
String mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";

try {
    MnemonicUtil.validateMnemonic(mnemonic);
    Account account = Account.createFromMnemonic(Networks.testnet(), mnemonic);
    System.out.println("Valid mnemonic, account created");
} catch (Exception e) {
    System.out.println("Invalid mnemonic phrase: " + e.getMessage());
}

Address Verification

// Verify account generates expected addresses
Account account = Account.createFromMnemonic(Networks.testnet(), knownMnemonic);
String expectedAddress = "addr_test1..."; // Known address for this mnemonic

if (account.baseAddress().equals(expectedAddress)) {
    System.out.println("Account verification successful");
} else {
    System.out.println("Account verification failed");
}

Error Handling

Handle common account-related errors:

try {
    Account account = Account.createFromMnemonic(Networks.mainnet(), userMnemonic);
    String address = account.baseAddress();
} catch (Exception e) {
    System.err.println("Account creation failed: " + e.getMessage());
}