Chialisp Code Reference

This document is a reference for the shipped Chialisp source. For the protocol-level design, see did:julia Technical Specification (Doc #15).

The Chialisp tree contains 27 production/build puzzle files (.clsp), 9 shared library files (.clib), two precompiled Chia singleton hex files, and a Makefile.

All source paths below are relative to the public Chialisp repository root.

1. Codebase Organization

1.1 Build Order

The repository includes a Makefile that builds the puzzles in the correct order. This matters because many puzzles embed compiled hashes of other puzzles with embed-file; a parent puzzle cannot be compiled until the child puzzle hashes it embeds already exist.

That is the only build rule this reference relies on: use the Makefile rather than compiling files by hand in arbitrary order.

1.2 How DID Spends Route

The main DID singleton puzzle, julia_did.clsp, is the first puzzle run for a DID spend. After checking the DID state hash and lineage, it routes to one of seven top-level entrypoints:

Normal authentication entrypoints can call two kinds of child operations:

• combineable operations, which can continue to another child puzzle
• standalone operations, which perform one action and stop

1.3 Combineable Operations

The combineable operations have a required invocation order:

sign_message
  -> coin_control
    -> invalidate
      -> DIDdoc_announce
        -> pass_thru
          -> present_delegated
            -> present_claims

Any combineable operation can be skipped. For example, authenticated callers can call present_claims directly; sign_message can call present_claims directly; DIDdoc_announce can call present_delegated directly. The chain above shows the order when all combineable operations are used together.

Each wrapper prepends its own conditions before passing through child conditions:

1.4 Standalone DID Operations

These operations are called individually by an authentication entrypoint and do not continue into the wrapper chain.

1.5 Recovery Paths

Recovery has two distinct call patterns. Four recovery puzzles are direct entrypoints selected by julia_did.clsp, bypassing normal authentication. recovery_authorize.clsp is different: it is a standalone operation called by the recovery-agent DID through singlesig or multisig.

1.6 Issuer Key and Companion Coin Interactions

Issuer key singletons are separate from the DID singleton:

• launch_issuer_key.clsp is a DID operation that creates issuer key singleton launchers.
• issuer_key.clsp is the issuer key singleton puzzle.
• issuer_key_functions.clsp implements issuer key management modes for revocation updates and melt.
• issuer_key_control.clsp is the DID-side operation that sends commands to issuer key singletons.

Companion coin puzzles are not DID sub-puzzles:

• p2_JDID.clsp is used as an inner puzzle for coins controlled by a DID. It spends only when it receives a JDIDP command from the owning DID.
• p2_claim.clsp is used as an inner puzzle for coins controlled by a qualifying credential presentation and a DID command.
• faucet_coin.clsp is an independent faucet puzzle and is not part of the DID call graph.

1.7 Common Return Convention

Most sub-puzzles are called with:

(curried-args solution)

They return:

(updated-curried-args conditions)

The top-level julia_did.clsp consumes that return value, creates the next singleton generation with the updated curried-args hash, and emits the returned conditions. Leaf operations that do not change DID state return the original curried-args.

1.8 DID Curried Arguments

The DID singleton state is passed through the codebase as curried-args:

julia_did.clsp and issuer_key.clsp are curried with CURRIED-ARGS-HASH, not the full state. The full state is revealed in the solution and checked with sha256tree.

1.9 Chialisp Conventions

• Most files include *standard-cl-26*.
• Uppercase names in a mod signature are curried parameters; lowercase names are solution parameters.
• embed-file imports compiled puzzle hashes, not source.
• Bare (x <code>) expressions raise integer errors.
• AGG_SIG_PUZZLE and ASSERT_MY_PUZZLEHASH are used in normal singleton spends for fast-forward-compatible authorization.
• ASSERT_MY_PARENT_ID appears in eve spends, where the launcher relationship is being established.

2. Puzzle Reference

2.1 Top-Level and Companion Puzzles

julia_did.clsp

Main DID singleton puzzle.

Mod signature: (CURRIED-ARGS-HASH curried-args parent-info solution)

State input: Verifies CURRIED-ARGS-HASH == sha256tree(curried-args).

Regular spend behavior:

• Destructures the DID curried args.
• Confirms launcher-coin-id == my-launcher-id.
• Computes valid entrypoint hashes for singlesig, multisig, custody_minion, recovery_initiate, recovery_cancel, recovery_complete, and recovery_prerotation.
• Runs the selected entrypoint through puzzle-selector.
• Emits ASSERT_MY_PUZZLEHASH.
• Creates the next DID singleton child with julia-DID-curried-puzzlehash(julia-DID-puzzlehash, sha256tree(new-curried-args)).
• Emits REMARK new-curried-args.
• Appends child conditions returned by the entrypoint.

Eve spend behavior:

• Asserts the singleton launcher as parent with ASSERT_MY_PARENT_ID.
• Creates the first DID singleton child.
• Emits REMARK curried-args.
• Sends JDIDL to the prelauncher coin.

Errors: 15 failed lineage proof; 16 invalid curried args hash.

prelauncher.clsp

Prelauncher for Julia DID coins and root of the fast-forward lineage proof.

Mod signature: (PUBKEY julia-did-puzzlehash my-coin-id did-coin-curried-args-hash)

Conditions emitted:

• ASSERT_MY_COIN_ID my-coin-id
• CREATE_COIN singleton_launcher 1
• RECEIVE_MESSAGE 0x3F "JDIDL" did-coin-id

The puzzle is curried with PUBKEY; the remaining values are solution parameters.

p2_JDID.clsp

Inner puzzle for coins owned by a Julia DID.

Mod signature: (JDID_LAUNCHER_ID JDID-curried-args-hash conditions)

Behavior:

• Computes the owning DID coin puzzle hash from julia_did.clsp.hash.bin, the DID launcher ID, and the DID curried-args hash.
• Requires RECEIVE_MESSAGE 0x17 (concat "JDIDP" (sha256tree conditions)) <owning-DID-puzzlehash>.
• Emits the supplied conditions.

This puzzle does not validate the business meaning of the emitted conditions; it trusts the owning DID's authenticated coin_control path.

p2_claim.clsp

Inner puzzle for coins controlled by possession of a valid credential claim.

Mod signature: (JDID_LAUNCHER_ID my-coin-id spender-launcher-id spender-curried-args-hash conditions)

Behavior:

• Asserts its own coin ID.
• Computes the spender DID puzzle hash.
• Requires an asserted puzzle announcement from the spender DID proving a JDIDV claim for the hardcoded payment property sha256("cleartext://./.julia-payment"), this coin ID, and the payee DID launcher ID.
• Requires RECEIVE_MESSAGE 0x17 (concat "JDIDP" (sha256tree conditions)) <spender-DID-puzzlehash>.
• Emits the supplied conditions.

faucet_coin.clsp

Simple faucet coin puzzle used by the Julia Social faucet.

Mod signature: (PUBKEY SERIAL conditions)

SERIAL allows multiple otherwise-identical faucet coins to be created. The puzzle emits the supplied conditions only when authorized by:

(AGG_SIG_ME PUBKEY (sha256tree conditions))

Unlike the DID puzzles, this puzzle uses AGG_SIG_ME, binding authorization to the specific coin spend.

2.2 Authentication Entry Points

singlesig.clsp

Single-key authentication entrypoint.

Mod signature: (curried-args solution)

Solution shape: fee-coin, one pubkey Merkle path, sides, and child puzzle input.

Validation:

• DID must require exactly one class.
• Exactly one pubkey path must be supplied.
• The path must validate against multisig-info.
• The selected class must require exactly one member.
• Recovery must not be active.

Conditions added:

• AGG_SIG_PUZZLE <pubkey> (sha256tree solution)
• Optional ASSERT_CONCURRENT_SPEND fee-coin

Allowed children: sign_message, coin_control, custodian, DIDdoc_announce, DIDdoc_set, invalidate, issuer_key_control, launch_issuer_key, pass_thru, present_claims, present_delegated, rekey, recovery_authorize.

Errors: 30, 31, 32, 33, 34, plus 110 from puzzle-selector.

multisig.clsp

Multi-signer, multi-class authentication entrypoint.

Mod signature: (curried-args solution)

Solution shape: fee-coin, participant Merkle paths, path sides, and child puzzle input.

Validation:

• Uses multiclass to validate participants against multisig-info.
• Recovery must not be active.
• Child puzzle hash must be in the allowlist.

Conditions added:

• One AGG_SIG_PUZZLE <pubkey> (sha256tree solution) per validated participant.
• Optional ASSERT_CONCURRENT_SPEND fee-coin.

Allowed children: Same as singlesig.clsp.

Errors: 17, plus 103-106 from multiclass and 110 from puzzle-selector.

custody_minion.clsp

Authentication entrypoint for DIDs controlled by an external custodian DID.

Mod signature: (curried-args solution)

Solution shape: custodian DID launcher ID, custodian curried-args hash, and child puzzle input.

Validation:

• The custodian DID must appear in valid-custodian-DIDs.
• Recovery must not be active.
• Requires RECEIVE_MESSAGE 0x12 (concat "JDIDC" child-solution-hash) <custodian-DID-puzzlehash>.
• Asserts this minion DID's current puzzle hash.

Allowed children: sign_message, coin_control, DIDdoc_announce, DIDdoc_set, invalidate, issuer_key_control, launch_issuer_key, pass_thru, present_claims, present_delegated.

Errors: 5, 6, plus 110 from puzzle-selector.

2.3 DID Operation Puzzles

sign_message.clsp

Adds DID-signed message announcements, timestamps, and nonces, then optionally delegates.

Mod signature: (curried-args solution)

Solution shape: messages list, datetime, nonce, optional child puzzle input.

Conditions added:

• One CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDM" message) per message.
• Optional CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDT" datetime).
• Optional CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDN" nonce).

Allowed children: coin_control, DIDdoc_announce, invalidate, pass_thru, present_claims, present_delegated.

Errors: 110 for invalid child.

coin_control.clsp

Sends DID-authorized command messages to other coins.

Mod signature: (curried-args solution)

Solution shape: count, count pairs of message and coin ID, then optional child puzzle input.

For each pair, emits:

(SEND_MESSAGE 0x17 (concat "JDIDP" message) coin-id)

The code does not check whether the receiving coin uses p2_JDID or p2_claim; it only emits the command message.

Allowed children: DIDdoc_announce, invalidate, pass_thru, present_claims, present_delegated.

Errors: 110 for invalid child.

invalidate.clsp

Adds conditions that make a spend bundle unusable on-chain while preserving verifiability.

Mod signature: (curried-args solution)

Solution shape: invalidate-flag, valid-from-seconds, valid-to-seconds, optional child puzzle input.

Conditions added:

• If invalidate-flag is truthy: ASSERT_CONCURRENT_SPEND on the all-zero coin ID.
• If valid-from-seconds is set: ASSERT_SECONDS_ABSOLUTE.
• If valid-to-seconds is set: ASSERT_BEFORE_SECONDS_ABSOLUTE.

Allowed children: DIDdoc_announce, pass_thru, present_claims, present_delegated.

Errors: 110 for invalid child.

DIDdoc_announce.clsp

Announces the DataLayer singleton ID associated with the DID Document.

Mod signature: (curried-args solution)

Condition added:

(CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDD" DID-doc))

Allowed children: pass_thru, present_claims, present_delegated.

Errors: 110 for invalid child.

DIDdoc_set.clsp

Updates the DID Document pointer.

Mod signature: (curried-args solution)

Solution shape: new-DID-doc.

State change: Replaces the DID-doc field in curried-args.

Conditions added: none.

pass_thru.clsp

Allows arbitrary caller-supplied conditions after guarding the JDID namespace.

Mod signature: (curried-args solution)

Solution shape: count, count conditions, optional child puzzle input.

Validation:

• Rejects structured coin/puzzle announcements.
• Rejects coin/puzzle announcements whose byte content starts with JDID.
• Rejects structured SEND_MESSAGE payloads.
• Rejects SEND_MESSAGE payloads whose byte content starts with JDID.

Allowed children: present_claims, present_delegated.

Errors: 18, 19, 20, 21, 36.

custodian.clsp

Allows a custodian DID to command a custodied DID that uses custody_minion.clsp.

Mod signature: (curried-args solution)

Solution shape: minion DID launcher ID, minion curried-args hash, child solution hash.

Conditions added:

• SEND_MESSAGE 0x12 (concat "JDIDC" child-solution-hash) <minion-DID-puzzlehash>
• ASSERT_MY_PUZZLEHASH <this-DID-puzzlehash>

State change: none.

rekey.clsp

Routine key update using current authentication.

Mod signature: (curried-args solution)

Solution shape: new-multisig-info.

State change: Replaces the multisig-info field.

Conditions added: none.

2.4 Recovery Puzzles

recovery_initiate.clsp

Starts a time-locked recovery by committing pending replacement state.

Mod signature: (curried-args solution)

Solution shape: participant Merkle paths, participant curried-arg hashes, new multisig info, new custodian DID list, new recovery info.

Validation:

• Recovery must not already be active.
• Participants must satisfy recovery-info via multiclass.
• Participant and curried-arg-hash lists must balance.

State change:

• Sets recovery-timeout-block to the configured recovery delay.
• Appends pending replacement values: new multisig info, new custodian DIDs, and new recovery info.

Conditions added: One RECEIVE_MESSAGE 22 (concat "JDIDR" new-params-hash) <participant-DID-puzzlehash> per required recovery participant.

Errors: 27, 28, 29, plus multiclass and Merkle-path errors.

recovery_authorize.clsp

Run by a recovery participant DID to authorize initiation or cancellation on another DID.

Mod signature: (curried-args solution)

Solution shape: target DID launcher ID, target curried-args hash, initiate-or-cancel, new-params-hash, expiration-block.

State change: Appends a trailing 0 marker to its own curried args.

Conditions added:

• SEND_MESSAGE 22 (concat "JDID" initiate-or-cancel new-params-hash) <target-DID-puzzlehash>
• ASSERT_BEFORE_HEIGHT_ABSOLUTE expiration-block

initiate-or-cancel must be "R" or "X".

Errors: 22.

recovery_cancel.clsp

Cancels an active recovery.

Mod signature: (curried-args solution)

Solution shape: participant Merkle paths and participant curried-arg hashes.

Validation:

• Recovery must be active.
• Participants must satisfy recovery-info.
• Participant and curried-arg-hash lists must balance.

State change: Resets recovery-timeout-block to 0 and removes pending recovery state.

Conditions added: One RECEIVE_MESSAGE 22 "JDIDX" <participant-DID-puzzlehash> per required recovery participant.

Errors: 23, 24, 25, plus multiclass and Merkle-path errors.

recovery_complete.clsp

Completes an active recovery after the delay.

Mod signature: (curried-args solution)

Validation: Recovery must be active.

State change: Applies pending new-multisig-info, new-custodian-DIDs, and new-recovery-info; resets recovery delay to 0.

Conditions added: ASSERT_HEIGHT_RELATIVE recovery-delay.

Anyone can spend this puzzle once the relative height condition can be satisfied.

Errors: 26.

recovery_prerotation.clsp

Switches immediately to a pre-committed key configuration and commits the next prerotation.

Mod signature: (curried-args solution)

Solution shape: fee coin, participant Merkle paths, path sides, new prerotation multisig info.

Validation: Participants must satisfy the prerotation multisig info stored inside recovery-info.

State change:

• Replaces multisig-info with the previous prerotation multisig info.
• Stores the supplied next prerotation info inside recovery-info.
• Cancels any active recovery by setting recovery delay to 0.

Conditions added:

• One AGG_SIG_PUZZLE <pubkey> (sha256tree solution) per prerotation signer.
• Optional ASSERT_CONCURRENT_SPEND fee-coin.

2.5 Issuer Key Puzzles

launch_issuer_key.clsp

Creates issuer key singleton launchers from the owning DID.

Mod signature: (curried-args solution)

Solution shape: DID parent, DID launcher ID, raw issuer-key puzzle hash, followed by one or more issuer key definitions: public key, valid-from, valid-to, maximum credential expiration, allowed property root, mode-1 payment puzzle hash, mode-1 payment mojos.

Conditions added per key:

• CREATE_COIN singleton_launcher amount
• RECEIVE_MESSAGE 0x3F "JDIDI" <issuer-key-coin-id>

Additional condition: ASSERT_MY_COIN_ID my-coin-id.

Implementation note: Launcher coin amounts increase across multiple launches while issuer key singleton children use amount 1.

Error: 41 if mode-1-payment-mojos > 1, blocking free anyone-can-spend payment coins.

issuer_key.clsp

Issuer key singleton puzzle.

Mod signature: (CURRIED-ARGS-HASH curried-args parent-info spend-mode spend-mode-args)

Issuer key curried args:

1. issuer-did-launcher-id
2. issuer-key-puzzlehash
3. julia-did-puzzlehash
4. my-launcher-id
5. public-key
6. revocation-bitfield-root
7. valid-from
8. valid-to
9. max-expiration
10. cred-property-hash-root
11. mode-1-payment-puzzlehash
12. mode-1-payment-mojos

Eve spend behavior:

• ASSERT_MY_PARENT_ID launcher-coin-id
• Creates the first issuer key singleton child.
• Emits REMARK curried-args.
• Sends JDIDI to the issuer DID coin.

Regular spend behavior:

• Checks CURRIED-ARGS-HASH.
• Verifies launcher lineage.
• Emits ASSERT_MY_PUZZLEHASH.
• Mode 1: recreates the singleton unchanged, emits REMARK curried-args, emits CREATE_PUZZLE_ANNOUNCEMENT "JDIDA", and optionally creates the configured payment coin.
• Other modes: require issuer_key_functions.clsp as the spend-mode puzzle and delegate to it.

Errors: 9, 10, 11, 42.

issuer_key_functions.clsp

Management functions for an issuer key singleton.

Mod signature: (curried-args spend-mode spend-mode-args)

Mode 2: update revocation by key

• Verifies current bitfield proof.
• Replaces one bitfield leaf and computes the new root.
• Requires AGG_SIG_PUZZLE public-key (sha256tree spend-mode-args).
• Creates the next issuer key singleton child and emits REMARK new-curried-args.
• Optionally asserts a concurrent fee coin.

Mode 3: update revocation by DID

• Verifies current bitfield proof.
• Replaces one bitfield leaf and computes the new root.
• Requires RECEIVE_MESSAGE 0x16 (concat "JDIDK" (sha256tree (list index new-leaf))) <issuer-DID-puzzlehash>.
• Creates the next issuer key singleton child and emits REMARK new-curried-args.

Mode 5: melt

• Requires RECEIVE_MESSAGE 0x12 "JDIDZ" <issuer-DID-puzzlehash>.
• Emits the Chia singleton melt CREATE_COIN 0 -113.

Errors: 12, 13, 14.

issuer_key_control.clsp

DID-side issuer key management operation.

Mod signature: (curried-args solution)

Solution shape: mode plus mode-specific target issuer key values.

Mode 3: Emits SEND_MESSAGE 0x16 (concat "JDIDK" (sha256tree (list index new-leaf))) <issuer-key-puzzlehash>.

Mode 5: Emits SEND_MESSAGE 0x12 "JDIDZ" <issuer-key-puzzlehash>.

State change: none.

Error: 35 for invalid mode.

2.6 Credential Presentation Puzzles

present_claims.clsp

Validates and presents credential claims.

Mod signature: (curried-args solution)

Solution shape: nonce plus claims-with-proofs.

Behavior:

• Emits CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDN" nonce).
• Calls validate-claims with this DID launcher ID, the raw julia_did puzzle hash, the raw issuer_key puzzle hash, and the supplied claims-with-proofs.
• Returns unchanged curried-args.

See include/validate_claims.clib for per-claim validation details.

present_delegated.clsp

Presents claims delegated through one or more DID holders.

Mod signature: (curried-args solution)

Solution shape: count, delegation paths, optional present_claims child input.

Behavior:

• Asserts the original claim's holder/delegation announcement.
• Walks each delegation path.
• Requires the terminal delegatee to be this DID.
• Emits CREATE_PUZZLE_ANNOUNCEMENT (concat "JDIDV" claim-property-hash claim-value-hash issuer-did-launcher-id) for delegated presentation as subject.
• Optionally runs present_claims.clsp as a child to present original claims in the same spend.

Errors: 37, 38, 39.

3. Library Reference

include/sha256tree.clib

Recursive CLVM tree hash implementation:

• Atom: sha256(1, atom)
• Pair: sha256(2, sha256tree(left), sha256tree(right))

include/condition_codes.clib

Defines Chia condition constants used throughout the codebase, including signature, coin creation, announcements, messaging, self-inspection, relative/absolute time assertions, and REMARK.

include/curry_and_treehash.clib

Computes the puzzle hash of a curried function without performing the curry. Used by did_puzzles.clib to reconstruct expected DID and issuer key puzzle hashes inside other puzzles.

include/did_puzzles.clib

Puzzle hash helpers:

• prelauncher-coin-puzzlehash
• issuer-key-curried-puzzlehash
• issuer-key-coin-puzzlehash
• julia-DID-curried-puzzlehash
• julia-DID-coin-puzzlehash

Embeds the standard singleton top layer and singleton launcher hashes.

include/puzzle_selector.clib

Generic allowlist router. It compares a supplied puzzle hash against valid hashes and executes the puzzle if matched. Raises 110 when no match is found.

include/parse_merkle_path.clib

Validates a Merkle path and extracts (class . leaf). Raises 107 for class depth beyond leaf depth, 108 for invalid class depth, and 109 for root mismatch.

include/multiclass.clib

Validates multi-class quorum requirements. It parses participant Merkle paths, verifies class membership, enforces unique participant leaves, and checks that enough classes are satisfied.

Errors: 103, 104, 105, 106.

include/bitfield.clib

Revocation bitfield utilities:

• verify-tree
• check-bit
• set-leaf

Errors: 100 offset too large, 101 negative offset, 102 invalid tree proof.

include/validate_claims.clib

Credential claim validation logic. For each claim, validates subject/holder mode, issuer DID consistency, public-key consistency, expiration bounds, issuer-key validity period, revocation status, property authorization, and antecedent requirements.

Per valid claim it emits claim/holder announcements, asserts issuer-key liveness via JDIDA, adds time-window assertions, and requires AGG_SIG_UNSAFE from the issuer key over the claim tree hash.

Error: 112 claim validation failed.

4. Error Codes

5. File Inventory

5.1 Production/Build Puzzles

5.2 Libraries

5.3 Other Build Files

View this page as Markdown