Skip to main content

Inner Puzzles

Owner coins are protocol coins that have operations that can only be performed by a designated owner:

  • Collateral vaults (owner & keeper)
  • Savings vaults (owner)
  • Governance coins (owner & keeper)
  • Announcers (owner & keeper)

Apart from Savings vaults, all protocol coins are also keeper coins, i.e. have at least one operation that can be performed by arbitrary third parties.

Namespacing spends​

To spend a protocol coin, an inner puzzle and corresponding inner solution must be provided in the solution. Owner coins have a curried arg INNER_PUZZLE_HASH, which is used to verify that owner operations can only be performed by the legitimate owner of the coin. This is done by asserting that the hash of the inner puzzle provided in the solution matches the curried inner puzzle hash.

Savings vaults are an exception to the above. Since these don't have keeper operations, all spend paths require a reveal of the owner's inner puzzle. Therefore an INNER_PUZZLE curried arg holds the whole inner puzzle instead of only the inner puzzle hash.

To spend the coin on an owner spend path, the inner puzzle must be revealed and a corresponding inner solution passed in. To spend a coin on a keeper spend path, an arbitary inner puzzle and corresponding solution can be passed in. The purpose of the inner puzzle in this case is not to verify the legitimacy of the spend but to namespace it, allowing a keeper to tie multiple coin spends together. A simple example would be to add a fee coin to a protocol operation bundle.

Inner puzzle requirements​

Running an inner puzzle with its corresponding inner solution results in a list of inner conditions. These conditions are then filtered by the following functions:

  • Announcers and Savings vaults: filter-and-extract-unique-create-coin (create coin)
  • Collateral vaults, treasury, oracle, recharge and surplus auctions, and payout coins: filter-and-extract-remark-solution (solution remark)
  • Announcer Registry: find-solution-remark-value (solution remark)
  • Governance coins: filter-conditions (create coin & solution remark)

The four functions fulfil two common key purposes, namely to block protocol conditions from being output by the inner puzzle and to extract solution args needed by the protocol coin layer.

Solution args are extracted from a solution condition, which is either a CREATE_COIN or a solution remark condition, respectively, except in the case of governance coin spends, which require both. A solution remark condition is a REMARK condition with SOLUTION_PREFIX ("S") in second position:

(REMARK SOLUTION_PREFIX ...)

The filter functions return information extracted from the solution condition(s) together with all other conditions that were generated by the inner puzzle. This means that a general purpose inner puzzle must be chosen so that it can simultaneously:

  • not output any protocol conditions
  • output exactly one or both solution conditions The inner puzzle should ideally be able to output solution conditions of arbitrary form, so that there is no limitation on what spends are possible.

The standard transaction puzzle fulfils those criteria, making it safe to use as inner puzzle for all protocol coins. This is also what the app does.