Julia-DID Chialisp

Smart contracts for Julia.social decentralized identifiers on the Chia blockchain.

Overview

Julia-DID implements decentralized identifiers (DIDs) as Chia singletons. The top-level DID puzzle delegates to sub-puzzles for authentication, key management, recovery, credential issuance, and credential presentation. Puzzles are designed for fast-forward compatibility — concurrent spends that don't change curried args won't conflict.

The DID supports multiple authentication modes (single-key, multi-key with class requirements, and external custody), time-locked key recovery with prerotation, verifiable credential issuance via issuer key singletons, and credential presentation including delegated claims.

Architecture

The DID singleton delegates to an authentication puzzle, which then routes through a chain of wrapper puzzles before reaching the target operation:

julia_did → singlesig / multisig / custody_minion
  - sign_message
    - coin_control
      - invalidate
        - DIDdoc_announce
          - pass_thru
            - present_delegated
              - present_claims

Sub-puzzle Categories

• Authentication: singlesig, multisig, custody_minion
• Recovery: recovery_initiate, recovery_authorize, recovery_cancel, recovery_complete, recovery_prerotation
• Credentials: present_claims, present_delegated
• Key management: issuer_key, issuer_key_control, issuer_key_functions, launch_issuer_key
• Operations: sign_message, coin_control, invalidate, pass_thru, rekey
• DID document: DIDdoc_announce, DIDdoc_set
• Companion: p2_JDID, p2_claim

Build Dependencies

Puzzles embed compiled hashes of their dependencies (not source), creating a strict build dependency graph. The Makefile enforces the correct compilation order.

Directory Structure

• *.clsp — puzzle source files (*_test.clsp are test fixtures, not deployed puzzles)
• *.clsp.hex — pre-compiled standard Chia puzzles (singleton launcher and top layer)
• include/*.clib — shared library files
• tests/ — the test suite (see tests/README.md)
• scripts/ — build and test helper scripts
• output/ — build artifacts (generated)

Prerequisites

The Rust-based chialisp CLI tools run, brun, opc, and opd must be on PATH — all provided by the chialisp crate — plus curry for the test suite:

Both are pinned: the puzzle hashes below are the compiler's output, so a different compiler version can produce different hashes from identical source.

cargo install chialisp --version 0.4.5
cargo install --git https://github.com/rigidity/curry --rev 28bd02e6be08de73c312256a5b1d34c31bcb7ba0

The build also uses xxd, which ships with most Unix systems (part of the vim package on many Linux distributions).

Building and Testing

make           # Compile all puzzles (order-dependent build)
make test      # Build everything, then run the full test suite
make clean     # Remove all build outputs

The suite is 296 tests across 35 per-puzzle directories, covering happy paths with exact condition-shape assertions, negative tests for every raise site, adversarial characterizations, cross-puzzle message-pairing tests, and an external ground-truth harness that validates the puzzle-hash helpers against real currying. See tests/README.md for the test-case file conventions, and:

./scripts/mod_test <file>.clsp              # Run all tests for one puzzle
./scripts/mod_test <file>.clsp <testname>   # Run a single named test

To compile a single puzzle:

./scripts/mod_compile <file>.clsp

Compiled artifacts land in output/: for each puzzle, its CLVM form (.clvm), serialized hex (.hex), tree hash (.hash), and binary tree hash (.hash.bin, embedded by dependent puzzles).

Puzzle Hashes

Tree hashes of the compiled puzzles, for verifying that a local build matches this release.

Puzzle	Tree hash
coin_control	cbf39fdd6fbe207ec8e690b2e7ee3d3c04607196ecee9851f90c842b32b48537
custodian	6a6a53288bc5ae3c7d4cca8c0025d7fffc058c8610e6d1f28c6988830178a2f7
custody_minion	597415b279e37b674f7c1712dcde98ff41525c6ca815716c9fdca5da6b630af1
DIDdoc_announce	1a9ba4490df5a4b3fab26333fa8e6149f0065be0a55e7ef400896b28c2af3480
DIDdoc_set	127b9a2fb92f5386eb95ecd910567f4120eb4d9744101ac9e2a7d83f5265a336
faucet_coin	7a45acf0e1dd9c717ae4acb38473e66952a44b920cb56b95cd60dbc8a7dd24d4
invalidate	f0d86e1b4c7c952b85d250eb92703b01020d52093b5d7a64acf07db87df9b2b4
issuer_key	daf844849881c3fb389d829aaf8cd05001e8862d8a0dd26e304986b0590989ff
issuer_key_control	18c6998efbfcb3679219b2f62feebf3e9d7ad1c5c511cc8fe2d693f057915bf5
issuer_key_functions	3305e5c61f4cde755109c5a5c2d92e2a0849f3f65babcae131714d3852779b2e
julia_did	86361d36c86f3eb892a39b09539fda6d424628a4c7e25d6a4375efa5c4923fa1
launch_issuer_key	f7b881117107bc93c8dc089e4b7ab734f5456c447f3c89a4ac739031c08c7a42
multisig	951e25e46a5c0322bfa252838337d50a7481e87362387d759ddf0d635741b328
p2_claim	3e2708fde7405f82d06121163533307b1c960b0b21da8f4f8c500a716c559a61
p2_JDID	3c6263983ac621e0aede43d3aea2f140d6077aaa2f6b0a3a657abdc5aaaca230
pass_thru	c6c7601f55b6a0bd282f8b26d4a6a3d4a99934e313c38918c5122e7e3c6a0aed
prelauncher	0ae8147842334ad8915e35ea63ba80a96b1179c43695afd6102954cd8f9d32d9
present_claims	f88047ab666408d85eace413dd821be91221fbb51925ce6e3695b7bcdf0e376f
present_delegated	bce2f713c9d65fd8055f729c32998d9b60e4079126ed82f7e54c7dd51a2f6019
recovery_authorize	87daba68c8db42790a554d7d2ad25f1c78320079ae9b767a15136dea50d2ae65
recovery_cancel	32424505dc7e3b732c1f782c04f8cb1e72910f3cec6972affbc5371b6d1a8cc5
recovery_complete	2dbae5830eee754faaef0448e3db038f8145a033c21a4a15ee00b018a49f27d9
recovery_initiate	66043eaf12fd6a434efeefcdb3ac6b0ed91c0cb6159219dc73b72d94fea57df4
recovery_prerotation	3aced81c44e5dccaaba10673ae127cf8d3f1f5d276c3fb3a92b24c6871046673
rekey	47fc96435ef8f510457f70f5a2722208d6485168273eefd2eaf6565292b97cd3
sign_message	2ddbdb3ce5461d9dfe7c92b04d84b145868f6b11139ff2dad090c81842854f18
singlesig	afff1fd5e7a0e0d36831c61c41063584816adbf40f0ebda91b47e33a360c9ece
singleton_launcher	eff07522495060c066f66f32acc2a77e3a3e737aca8baea4d1a64ea4cdc13da9
singleton_top_layer_v1_1	7faa3253bfddd1e0decb0906b2dc6247bbc4cf608f58345d173adb63e8b47c9f

Security

The puzzles in this repository have been independently reviewed, but have not undergone a formal third-party security audit. To report a vulnerability, please follow the responsible disclosure process in SECURITY.md.

Contributing

This repository is published for transparency and review; we are not accepting pull requests. See CONTRIBUTING.md.

License

Copyright 2026 Julia.Social, Inc.

Licensed under the Apache License, Version 2.0.