Skip to main content

Overview

The Technical Manual is intended for advanced users, keepers, and Oracle data providers that would like to gain an in-depth understanding of the inner workings of the protocol.

For every protocol component, the manual explains what their purpose is and which puzzles are involved.

Protocol coins​

Coins that are part of the protocol are referred to as protocol coins. The diagram below gives a high-level overview of how protocol coins interact with each other.

Protocol overview

List of protocol coins​

Below is a complete list of protocol coin types. All protocol coins are singletons. Some protocol coins are unique, i.e. only one instance of the same type exists in the entire protocol, whereas there can be multiple instances of others. Unique singletons only hold a nominal amount (0 or 1 mojos), whereas the amount of other coins can vary. Some coins have an owner, which means that some or all operations on the coin can be performed only by the owner, whereas other coins can be spent by certain third parties or, in some cases, by anyone.

Ordinary Bytecash (BYC) and governance (CRT) coins are not considered protocol coins.

Operations​

For each protocol coin page deals with operations that can be performed on a given protocol coin. Operations are grouped by who can perform them.

  • Owner: The person that owns or controls a coin. Applies to:
    • Collateral vaults
    • Savings vaults
    • Announcers
    • Governance coins
  • Keeper: This can be anyone, but in practice are often professional trading firms that operate bots or automated trading infrastructure. Applies to:
    • Statutes
    • Oracle
    • Announcers
    • Announcer Registry
    • Collateral vaults
    • Recharge Auction
    • Surplus Auction
  • Governance: A group of CRT token holders. Governance operations require a corresponding governance coin spend. Applies to:
    • Statutes
    • Announcer
    • Treasury
    • Recharge Auction
    • Governance
  • Approval mod: One of the Approval mods is needed to authorise the operation. The corresponding Approval coin spend can be an owner, keeper or Announcer operation. Applies to:
    • Treasury
    • BYC Tail
    • CRT Tail
  • Announcer: An Announcer must authorise the operation. Excluding owner spends of the Announcer, this applies to:
    • Announcer Registry
  • Protocol deployer: The person/entity deploying the protocol. These operations must and can only be performed at protocol launch. Applies to:
    • Announcer Registry
    • CRT Tail
    • Statutes
    • Oracle (?)

For a visualisation of all operations and their interdependencies, see the inter-coin communication page.

State and Lineage​

On every page dedicated to a protocol coin type, there is a State and Lineage section which breaks down the curried args of the corresponding mod into fixed, immutable and mutable state variables, and provides information on eve state, amount of the coin, and required lineage proofs.

Fixed state​

Fixed state refers to mod args that are known prior to protocol deployment and are hardcoded into the mod itself. The hardcoding in done by currying fixed args into a raw mod before it is considered final.

For example, the raw treasury mod, treasury.clsp, has the following args:

CAT_MOD_HASH BYC_TAIL_MOD_HASH CRT_TAIL_MOD_HASH ; fixed args
MOD_HASH STATUTES_STRUCT LAUNCHER_ID ; immutable args
RING_PREV_LAUNCHER_ID ; mutable args

The first three args are all known prior to protocol deployment as they are simply hashes of other (raw) mods. Currying them turns the raw treasury mod into what is considered the treasury mod for protocol purposes.

Immutable state​

The first state variable following fixed args is always MOD_HASH. This is simply the hash of the mod with fixed args curried. Although MOD_HASH is known prior to protocol deployment, by convention it's not counted as a fixed arg, but considered part of the immutable state.

Other than MOD_HASH, immutable args are those that are not known prior to protocol deployment, but once curried cannot be changed again. This typically includes the STATUTES_STRUCT which only becomes known during protocol deployment as it contains the Statutes singleton's launcher coin ID, but can include other args as well. E.g. in the treasury mod example above, the treasury coin's launcher ID only becomes known when launching a new treasury coin.

Mutable state​

Mutable state consists of curried args that are subject to change during a coin spend. In the case of a treasury coins, there is only one such arg, but for most other protocol coins the mutable state comprises multiple curried args.