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.
Maestro does not store or log any sensitive wallet data. All generated keys are only visible in the endpoint response.
It is important to remember that these keys cannot be regenerated. Therefore, it is imperative to store this data with the highest level of safety and security.
The Wallet Manager service is available on the following blockchains:
Service | Bitcoin | Cardano | Dogecoin |
|---|---|---|---|
Wallet Manager | Coming Soon | Coming Soon |
Cardano HD wallets utilize the UTxO (unspent transaction output) accounting model, which 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 standards. 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.
- 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.
- 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.
- Seed Phrase Generation: When a new wallet is created, 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.
- 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).
- Hierarchical Structure: The keys can be organized hierarchically, allowing for a tree structure of accounts 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.
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 │ ┃ ┃ ┃ └───────────────────────┘ ┃ └───────────────────────┘ ┃ ┃ ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
- Header: The header describes the type of address and the network it is for (eg, Mainnet or Preprod)
- Payment Credentials: The main functionality is to send or receive ADA. It controls how to spend from an address.
- 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
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 not to contain a delegation key; however, most wallet (verification key) addresses do include it 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:
- Verification Key Hash: This pertains to the "standard" public-private key pairs found in user wallets. A single owner (i.e., wallet) has control of funds or staking rights, depending on whether it's a payment or delegation credential.
- 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 as multi-sig 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:
Data | Purpose |
|---|---|
mnemonic | human readable sentence as a backup recovery seed (private) |
payment address | used to store, receive, and send money |
payment skey | highly sensitive payment address secret (private) signing key file |
payment vkey | public verification key file for the payment address (not sensitive; may be shared publicly) |
stake address | used to store and withdraw rewards, define the stake pool owner and rewards accounts, and specify the wallet's target stake pool delegation |
stake vkey | stake address public verification key file (not sensitive; may be shared publicly) |
stake skey | sensitive 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 |