Skip to main content
Version: v1.7.0

Wallet Manager

Maestro's Wallet Manager API is a set of utility tools for Cardano wallet key pairs and address generation specified by CIP 1852 - HD (Hierarchy for Deterministic) Wallets for Cardano.

caution

Maestro does not store or log any sensitive wallet data. All generated keys are only visible in the endpoint response. There is no way to regenerate the same keys, therefore please store this data with the utmost safety and security in mind.

Understanding Cardano Wallets

Cardano HD wallets utilize the UTxO (unspect transaction output) accounting model and is fundamentally different from Ethereum's account-based accounting model. It's important to first understand the key differences between these models before trying to understand the internals of Cardano wallets.

Furthermore, Cardano HD wallets support and extend both the BIP-0044 and BIP-0032 Bitcoin standard. The following sections will breakdown how a Cardano wallet is constructed and organized.

Wallet Key Pairs​

The bifurcation of wallet keys into public and private components in blockchain systems provides a balance between transparency and security. Public keys or addresses allow for transparent interactions in a decentralized ledger, while private keys ensure that only the rightful owner of assets can make decisions regarding their use or transfer.

  1. Public Key: Represents an identity on the blockchain (keyname.vkey).

    • Address Derivation: Derived from the public key, the address (keyname.addr) serves as the user's account on the blockchain. This address is used to receive funds or assets.
    • Safety: Both the public key and its derived address can be shared openly. They act as receiving endpoints, and knowledge of them does not grant control over the funds.
    • Verification: The public key is also essential for others in the network to verify the authenticity of a transaction signed by the corresponding private key.

  2. Private Key: Acts as a digital signature mechanism and grants control over assets associated with the corresponding public key (keyname.skey).

    • Transaction Signing: Any operation, like sending cryptocurrency, requires the transaction to be signed with the private key. This signature proves ownership and intent without revealing the private key itself.
    • Security: The private key must be kept confidential. Exposure compromises the security of the associated assets.
    • Irrecoverable: If a private key is lost, the assets associated with it become inaccessible. Conversely, if someone else gains access to it, they gain full control over those assets.

Hierarchical Deterministic (HD) Wallets​

HD wallet can derive multiple key pairs from a single master (root) key and allow the creation of a hierarchical tree of key pairs. The deterministic nature of key generation, combined with the hierarchical organization, allows for flexibility in managing multiple crypto assets within multiple accounts seamlessly, offering enhanced security, privacy, and convenience.

  1. Seed Phrase Generation: At the creation of a new wallet, a seed phrase (typically 12 or 24 words) is generated. This seed phrase is a human-readable representation of the wallet's master (root) private key.

  2. Derivation of Keys: Using this master private key, a series of child private keys (and associated public keys) can be derived in a deterministic manner. This is achieved using the Extended Key Derivation (BIP32) standard (CIP 3 - Wallet Key Generation).

  3. Hierarchical Structure: The keys can be organized hierarchically, allowing for a tree structure of accounts each containing multiple addresses. This is helpful, for instance, when a user wants to segregate funds or if a business wants to separate departments or functionalities.


                                             |--> Address [Network + Payment Key + Stake Key]      
                            |--> Account Key |
                            |                |--> Address [Network + Payment Key + Stake Key]
Seed Phrase |--> Master Key |
                            |                |--> Address [Network + Payment Key + Stake Key] 
                            |--> Account Key |
                                             |--> Address [Network + Payment Key + Stake Key]

Cardano Address Breakdown​

Cardano uses a unique approach to its wallet addresses, breaking them down into specific credentials to enhance both functionality and security. This separation facilitates a user's ability to keep funds secure while participating in staking.

 
┏━ Header ━━━━━━━┳━ Payment credentials ━━━━━━━┳━ Staking credentials ━━━━━━━┓
┃                ┃                             ┃                             ┃
┃                ┃  ┌───────────────────────┐  ┃  ┌───────────────────────┐  ┃
┃  ┌──────────┐  ┃  │ Verification key hash │  ┃  │ Verification key hash │  ┃
┃  │ Network  │  ┃  ├────────── OR ─────────┤  ┃  ├────────── OR ─────────┤  ┃
┃  └──────────┘  ┃  │      Script hash      │  ┃  │      Script hash      │  ┃
┃                ┃  └───────────────────────┘  ┃  └───────────────────────┘  ┃
┃                ┃                             ┃                             ┃
┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  1. Header: The header describes the type of address and the network it is for (eg: Mainnet or Preprod)

  2. Payment Credentials: The main functionality is to send or receive ADA. It control how to spend from an address.

  3. Staking (Delegation) Credentials: These are concerned with the staking mechanics in the Cardano network. It's used to:

    • Collect rewards from staking
    • Define the stake pool owner and rewards accounts
    • Specify the wallet's delegation preferences
note

When constructing an address the delegation credential component is optional. This means any ADA present at that address will not be staked on the network. It is common for Script Hash addresses to not contain a delegation key, however most wallet (verification key) addresses do include it in order to earn staking rewards.

In Cardano, credentials associated with an address, whether they are for payment or delegation, can take on one of two forms:

  1. Verification Key Hash: This pertains to the "standard" public-private key pairs found in user wallets. A single owner (i.e.the wallet) has control of funds or staking rights, depending on whether it's a payment or delegation credential.
  1. Script Hash: Rather than being tied to a user wallet, this method ties the address to a specific script. The script defines the conditions under which the funds can be spent or staking operations can be performed. Scripts can implement more complex policies, such multisig transactions, smart contracts and various other operations.

In conclusion, while verification key hashes in Cardano offer a direct and clear-cut mechanism for asset ownership, script hashes provide a more adaptable and intricate way of defining control or ownership, making Cardano versatile and suitable for a wide array of applications.

Wallet Manager Data Breakdown​

When creating a new Cardano wallet the following sensitive wallet data is generated:

DataPurpose
mnemonichuman readable sentence as a backup recovery seed (private)
payment addressused to store, receive, and send money
payment skeyhighly sensitive payment address secret (private) signing key file
payment vkeypublic verification key file for the payment address (not sensitive; may be shared publicly)
stake addressused to store and withdraw rewards, define the stake pool owner and rewards accounts, and specify the wallet's target stake pool delegation
stake vkeystake address public verification key file (not sensitive; may be shared publicly)
stake skeysensitive stake address secret (private) signing key file that gives access to awards held in the stake address and the ability to delegate to a stake pool

Helpful Resources

tip

Where to next?​