Registration Transaction Metadata Format
This CIP details a transaction metadata format, used by Cardano's Project Catalyst for voter registrations.
Project Catalyst uses a sidechain for it's voting system. One of the desirable properties of this sidechain is that even if its' safety is compromised, it doesn't cause a loss of funds on Cardano mainnet. To achieve this, instead of using Cardano wallets' recovery phrase on the sidechain, we introduce the "voting key".
However, since Catalyst uses stake-based voting, a user needs to associate their mainnet Ada to their voting key. This can be achieved through a voter registration transaction.
We therefore need a voter registration transaction that serves three purposes:
- Registers a voting key to be included in the sidechain
- Associates Mainnet ada to this voting key
- Declare an address to receive Catalyst voting rewards
A voting key is simply an ED25519 key. How this key is created is up to the wallet, although it is not recommended that the wallet derives this key deterministicly from a mnemonic used on Cardano.
A Catalyst registration transaction is a regular Cardano transaction with a specific transaction metadata associated with it.
Notably, there should be four entries inside the metadata map:
Voting registration example:
// voting_key - CBOR byte array
// stake_pub - CBOR byte array
// reward_address - CBOR byte array
The entries under keys 1, 2, 3, and 4 represent the Catalyst voting key, the staking key on the Cardano network, the address to receive rewards, and a nonce, respectively. A registration with these metadata will be considered valid if the following conditions hold:
- The nonce is an unsigned integer (of CBOR major type 0) that should be monotonically rising across all transactions with the same staking key.
- The advised way to construct a nonce is to use the current slot number.
- This is a simple way to keep the nonce increasing without having to access the previous transaction data.
- The reward address is a Shelley address discriminated for the same network this transaction is submitted to.
To produce the signature field, the CBOR representation of a map containing a single entry with key
61284 and the registration metadata map in the format above is formed, designated here as
This data is signed with the staking key as follows: first, the blake2b-256 hash of
sign_data is obtained.
This hash is then signed using the Ed25519 signature algorithm. The signature metadata entry is added to the transaction under key 61285 as a CBOR map with a single entry that consists of the integer key 1 and signature as obtained above as the byte array value.
// signature - ED25119 signature CBOR byte array
This CIP is not to be versioned using a traditional scheme, rather if any large technical changes require a new proposal to replace this one. Small changes can be made if they are completely backwards compatible.
Catalyst Fund 3:
- added the
Catalyst Fund 4:
- added the
noncefield to prevent replay attacks;
- changed the signature algorithm from one that signed
sign_datadirectly to signing the Blake2b hash of
sign_datato accommodate memory-constrained hardware wallet devices.
It was planned that since Fund 4,
registration_signature and the
staking_pub_key entry inside the
key_registration field will be deprecated.
This has been deferred to a future revision of the protocol.
The described metadata format allows for the association of a voting key with a stake credential on a Cardano network.
Cardano uses the UTxO model so to completely associate a wallet's balance with a voting key (i.e. including enterprise addresses), we would need to associate every payment key to a voting key individually. Although there are attempts at this (see CIP-0008), the resulting data structure is a little excessive for on-chain metadata (which we want to keep small).
Given the above, we choose to only associate staking keys with voting keys. Since most Cardano wallets only use base addresses for Shelley wallet types, in most cases this should perfectly match the user's wallet.
A future change of the Catalyst system may make use of a time-lock script to commit ADA on the mainnet for the duration of a voting period.
The voter registration metadata in this method will not need an association with the staking key.
staking_pub_key map entry and the
registration_signature payload with key
61285 will no longer be required.
- This metadata format is implemented by at least 3 wallets
- This metadata format is used by Catalyst for at least 3 funds
- This format has been used up to and included Catalyst fund 10
- Author(s) to provide a schema cddl file
- See the schema file
- Author(s) to provide a test vectors file
- See test vector file
- Author(s) to provide a npm package to support the creation of this metadata format
This CIP is licensed under CC-BY-4.0.