trezor-firmware/common/protob/messages-cardano.proto

syntax = "proto2";
package hw.trezor.messages.cardano;

// Sugar for easier handling in Java
option java_package = "com.satoshilabs.trezor.lib.protobuf";
option java_outer_classname = "TrezorMessageCardano";

import "messages-common.proto";

/**
 * Values correspond to address header values given by the spec.
 * Script addresses are only supported in transaction outputs.
 */
enum CardanoAddressType {
    BASE = 0;
    BASE_SCRIPT_KEY = 1;
    BASE_KEY_SCRIPT = 2;
    BASE_SCRIPT_SCRIPT = 3;
    POINTER = 4;
    POINTER_SCRIPT = 5;
    ENTERPRISE = 6;
    ENTERPRISE_SCRIPT = 7;
    BYRON = 8;
    REWARD = 14;
    REWARD_SCRIPT = 15;
}

enum CardanoCertificateType {
    STAKE_REGISTRATION = 0;
    STAKE_DEREGISTRATION = 1;
    STAKE_DELEGATION = 2;
    STAKE_POOL_REGISTRATION = 3;
}

enum CardanoPoolRelayType {
    SINGLE_HOST_IP = 0;
    SINGLE_HOST_NAME = 1;
    MULTIPLE_HOST_NAME = 2;
}

/**
 * Structure representing cardano PointerAddress pointer,
 * which points to a staking key registration certificate.
 * @embed
 */
message CardanoBlockchainPointerType {
    required uint32 block_index = 1;
    required uint32 tx_index = 2;
    required uint32 certificate_index = 3;
}

/**
 * Structure to represent address parameters so they can be
 * reused in CardanoGetAddress and CardanoTxOutputType.
 * NetworkId isn't a part of the parameters, because in a transaction
 * this will be included separately in the transaction itself, so it
 * shouldn't be duplicated here.
 * @embed
 */
message CardanoAddressParametersType {
    required CardanoAddressType address_type = 1;                   // one of the CardanoAddressType-s
    repeated uint32 address_n = 2;                                  // BIP-32-style path to derive the spending key from master node
    repeated uint32 address_n_staking = 3;                          // BIP-32-style path to derive staking key from master node
    optional bytes staking_key_hash = 4;                            // staking key can be derived from address_n_staking, or
                                                                    // can be sent directly e.g. if it doesn't belong to
                                                                    // the same account as address_n
    optional CardanoBlockchainPointerType certificate_pointer = 5;  // a pointer to the staking key registration certificate
}

/**
 * Request: Ask device for Cardano address
 * @start
 * @next CardanoAddress
 * @next Failure
 */
message CardanoGetAddress {
    // repeated uint32 address_n = 1;                               // moved to address_parameters
    optional bool show_display = 2 [default=false];                 // optionally prompt for confirmation on trezor display
    required uint32 protocol_magic = 3;                             // network's protocol magic - needed for Byron addresses on testnets
    required uint32 network_id = 4;                                 // network id - mainnet or testnet
    required CardanoAddressParametersType address_parameters = 5;   // parameters used to derive the address
}

/**
 * Request: Ask device for Cardano address
 * @end
 */
message CardanoAddress {
    required string address = 1;    // Base58 cardano address
}

/**
 * Request: Ask device for public key corresponding to address_n path
 * @start
 * @next CardanoPublicKey
 * @next Failure
 */
message CardanoGetPublicKey {
    repeated uint32 address_n = 1;  // BIP-32 path to derive the key from master node
    optional bool show_display = 2; // optionally show on display before sending the result
}

/**
 * Response: Contains public key derived from device private seed
 * @end
 */
message CardanoPublicKey {
    required string xpub = 1;                               // Xpub key
    required hw.trezor.messages.common.HDNodeType node = 2; // BIP-32 public node
}

/**
 * Request: Ask device to sign Cardano transaction
 * @start
 * @next CardanoSignedTx
 * @next Failure
 */
message CardanoSignTx {
    repeated CardanoTxInputType inputs = 1;                     // inputs to be used in transaction
    repeated CardanoTxOutputType outputs = 2;                   // outputs to be used in transaction
    // optional uint32 transactions_count = 3;                  // left as a comment so we know to skip the id 3 in the future
    // optional uint32 network = 4;                             // replaced with protocol_magic
    required uint32 protocol_magic = 5;                         // network's protocol magic
    required uint64 fee = 6;                                    // transaction fee - added in shelley
    optional uint64 ttl = 7;                                    // transaction ttl - added in shelley
    required uint32 network_id = 8;                             // network id - mainnet or testnet
    repeated CardanoTxCertificateType certificates = 9;         // transaction certificates - added in shelley
    repeated CardanoTxWithdrawalType withdrawals = 10;          // transaction withdrawals - added in shelley
    // optional bytes metadata = 11;                            // replaced in Mary era with auxiliary data below
    optional uint64 validity_interval_start = 12;               // transaction validity start - added in allegra
    optional CardanoTxAuxiliaryDataType auxiliary_data = 13;    // transaction auxiliary data

    /**
     * Structure representing cardano transaction input
     */
    message CardanoTxInputType {
        repeated uint32 address_n = 1;  // BIP-32 path to derive the key from master node
        required bytes prev_hash = 2;   // hash of previous transaction output to spend by this input
        required uint32 prev_index = 3; // index of previous output to spend
        // left as a comment so we know to skip the id 4 in the future
        // optional uint32 type = 4;
    }
    /**
     * Structure representing cardano transaction output
     */
    message CardanoTxOutputType {
        optional string address = 1;                                    // target coin address in bech32 or base58
        // repeated uint32 address_n = 2;                               // moved to address_parameters
        required uint64 amount = 3;                                     // amount to spend
        optional CardanoAddressParametersType address_parameters = 4;   // parameters used to derive the address
        repeated CardanoAssetGroupType token_bundle = 5;                // custom assets - added in mary
    }

    message CardanoAssetGroupType {
        required bytes policy_id = 1;                  // asset group policy id
        repeated CardanoTokenType tokens = 2;          // asset name-amount pair
    }

    message CardanoTokenType {
        required bytes asset_name_bytes = 1;     // asset name as bytestring (may be either ascii string or hash)
        required uint64 amount = 2;        // asset amount
    }

    /**
     * Stake pool owner parameters
     */
    message CardanoPoolOwnerType {
        repeated uint32 staking_key_path = 1;   // BIP-32-style path to derive staking key of the owner
        optional bytes staking_key_hash = 2;    // owner's staking key if it is an external owner
    }

    /**
     * Stake pool relay parameters
     */
    message CardanoPoolRelayParametersType {
        required CardanoPoolRelayType type = 1;   // pool relay type
        optional bytes ipv4_address = 2;          // ipv4 address of the relay given as 4 bytes
        optional bytes ipv6_address = 3;          // ipv6 address of the relay given as 16 bytes
        optional string host_name = 4;            // relay host name given as URL, at most 64 characters
        optional uint32 port = 5;                 // relay port number in the range 0-65535
    }

    /**
     * Stake pool metadata parameters
     */
    message CardanoPoolMetadataType {
        required string url = 1;   // stake pool url hosting metadata, at most 64 characters
        required bytes hash = 2;   // stake pool metadata hash
    }

    /**
     * Stake pool parameters
     */
    message CardanoPoolParametersType {
        required bytes pool_id = 1;                           // stake pool cold public key hash (28 bytes)
        required bytes vrf_key_hash = 2;                      // VRF key hash (32 bytes)
        required uint64 pledge = 3;                           // pledge amount in lovelace
        required uint64 cost = 4;                             // cost in lovelace
        required uint64 margin_numerator = 5;                 // pool margin numerator
        required uint64 margin_denominator = 6;               // pool margin denominator
        required string reward_account = 7;                   // bech32 reward address where the pool receives rewards
        repeated CardanoPoolOwnerType owners = 8;             // pool owners list
        repeated CardanoPoolRelayParametersType relays = 9;   // pool relays list
        optional CardanoPoolMetadataType metadata = 10;       // pool metadata
    }

    /**
     * Structure representing cardano transaction certificate
     */
     message CardanoTxCertificateType {
        required CardanoCertificateType type = 1;                 // certificate type
        repeated uint32 path = 2;                                 // BIP-32 path to derive (staking) key
        optional bytes pool = 3;                                  // pool hash
        optional CardanoPoolParametersType pool_parameters = 4;   // used for stake pool registration certificate
    }
    /**
     * Structure representing cardano transaction withdrawals
     */
    message CardanoTxWithdrawalType {
        repeated uint32 path = 1;
        required uint64 amount = 2;
    }

    message CardanoCatalystRegistrationParametersType {
        required bytes voting_public_key = 1;
        repeated uint32 staking_path = 2;
        required CardanoAddressParametersType reward_address_parameters = 3;
        required uint64 nonce = 4;
    }

    message CardanoTxAuxiliaryDataType {
        optional bytes blob = 1;
        optional CardanoCatalystRegistrationParametersType catalyst_registration_parameters = 2;
    }
}

/**
 * Response: Serialised signed cardano transaction chunk
 * @next CardanoSignedTxChunkAck
 */
message CardanoSignedTxChunk {
    required bytes signed_tx_chunk = 1;         // serialised, signed transaction chunk
}

/**
 * Request: Serialised signed cardano transaction chunk acknowledgement
 * @next CardanoSignedTxChunk
 * @next CardanoSignedTx
 */
message CardanoSignedTxChunkAck {
}

/**
 * Response: Serialised signed cardano transaction
 * @end
 */
message CardanoSignedTx {
    required bytes tx_hash = 1;               // hash of the transaction body
    optional bytes serialized_tx = 2;         // deprecated since transaction is sent in chunks now - kept for backwards compatibility
}