Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (94 loc) · 7.47 KB

AGENTS.md

File metadata and controls

114 lines (94 loc) · 7.47 KB
Raw

AGENTS.md

Project: ecash-elements-exchange — Simplicity Exchange on Elements/Liquid

On-chain atomic settlement and automated market making for peer-to-peer asset trading on the Liquid (Elements) sidechain, using Blockstream's Simplicity smart contract language. The project comprises TWO on-chain contracts plus off-chain coordination:

  1. Order Book settlement contract (simf/order_book.simf) — off-chain order matching + on-chain atomic swap settlement (modeled on simplicity-contracts/.../option_offer.simf).
  2. AMM / CPMM micro-pool contract (simf/amm.simf) — on-chain constant-product market maker (K = x * y), ported from the Cauldron CPMM design (see docs/REF-CASHSCRIPT-CAULDRON.md).

The covenant capability set is documented in docs/RESEARCH.md (verified from the installed simc 0.7.1 jet catalog).

Engineering Agent Rules

  1. ONLY refactor file(s) after asking for the latest source(s).
  2. Provide a (single) relative cli command for ALL sources required.
  3. ONLY output full and complete sources after refactoring.
  4. ALWAYS output as terminal-ready heredoc commands.
  5. DO NOT TRUNCATE any sources. Use the MINIMUM DIFF required to complete the fix/change.
  6. Maintain 1:1 logic parity. Do not omit secondary logic like debug sections, fallbacks, or comments.
  7. ALWAYS include the relative file path in the header comment, ONLY for those files that support it (e.g. NO JSON).
  8. Every statement of fact MUST be accompanied by a direct source citation or verifiable file path.
  9. If you do not have absolute certainty about a fact, respond with: CONFIDENCE: 0 — I need the following verified before I proceed.

Tech Stack (Verified Installed)

Tool Version Path Repo
simc (SimplicityHL compiler) 0.7.1+ ~/.cargo/bin/simc https://github.com/BlockstreamResearch/SimplicityHL
hal-simplicity 0.2.0 ~/.cargo/bin/hal-simplicity https://github.com/BlockstreamResearch/hal-simplicity
lwk_cli 0.19.0 ~/.cargo/bin/lwk_cli https://github.com/Blockstream/lwk
elementsd v23.3.1 ~/.simplex/bin/elementsd https://github.com/ElementsProject/elements
elements-cli v28.99.0 /usr/local/bin/elements-cli https://github.com/ElementsProject/elements
simplex (smplx) 0.0.9 ~/.simplex/bin/simplex https://github.com/BlockstreamResearch/smplx
simplicityhl-lsp 0.1.3 ~/.cargo/bin/simplicityhl-lsp https://github.com/BlockstreamResearch/simplicityhl-lsp
rustc 1.97.1 — https://rust-lang.org

Project Structure (Expected)

ecash-elements-exchange/
├── AGENTS.md
├── README.md
├── Cargo.toml
├── Simplex.toml          # auto-generated by `simplex init`, manually edited
├── simf/                 # SimplicityHL source files (.simf)
│   ├── lib.simf          # shared covenant helpers (asset/amount/script checks, check_sig)
│   ├── order_book.simf   # order book settlement contract (to be written)
│   └── amm.simf          # CPMM micro-pool contract (Cauldron port, to be written)
├── src/
│   ├── lib.rs
│   ├── artifacts/        # compiled Simplicity programs (base64), by `simplex build`
│   ├── matching/         # off-chain order matching engine (Rust, Phase 4)
│   └── amm_aggregator/   # off-chain micro-pool aggregator (Rust, Phase 4)
├── tests/               # integration tests
└── docs/
    ├── HANDOFF.md       # detailed handoff document
    ├── RESEARCH.md      # covenant jet research findings (resolved open questions)
    ├── REF-CASHSCRIPT-CAULDRON.md  # CashScript/Cauldron reference (fetched)
    └── ref/             # fetched reference files (CashScript docs, Cauldron PDF)

Key Constraints

  1. Simplicity has NO loops or unbounded recursion. Iterating an order book on-chain is impractical.
  2. Architecture: Off-chain order matching + On-chain atomic settlement via Simplicity contracts.
  3. Each order is a standalone UTXO with its own contract instance.
  4. Contract parameters are baked at compile time via param:: — each order requires a separate compilation.
  5. Witness values are provided at spend time via witness:: and witness files (.wit).
  6. SimplicityHL is a work in progress. Not ready for production use.

Open Questions — ALL RESOLVED (see docs/RESEARCH.md for citations)

  1. What covenant jets are available in the current simc release for output introspection (asset ID, amount, script, destination of tx outputs)? — RESOLVED: jet::output_amount(i), jet::output_asset(i), jet::output_script_hash(i), jet::output_is_fee(i), jet::num_outputs(), jet::current_index() all available in the Elements (Liquid) jet environment (SimplicityHL/src/jet/elements.rs). Elements-only; absent from Core/Bitcoin.
  2. Can a contract verify a specific output sends a specific amount of a specific asset to a specific pubkey? — RESOLVED: asset+amount YES (via jet::output_amount(i) + eq_256/eq_64); destination only via script-hash (jet::output_script_hash(i)), NOT a raw pubkey.
  3. Is there support for issuing assets programmatically via Simplicity? — RESOLVED: NO. Issuance jets are read-only introspection/calculation; assets must be issued via Elements RPC / PSET issuance fields before contract funding.
  4. How does the taker destination address get specified? — RESOLVED: not baked; authorized by the taker's BIP-340 signature over jet::sig_all_hash() (free-destination pattern, as in option_offer.simf withdraw/expiry paths). Optionally bake a script-hash param:: for stricter enforcement.

Development Lifecycle

  1. Write .simf contract source.
  2. Compile: simc simf/order.simf --json
  3. Inspect: hal-simplicity simplicity info <base64-program>
  4. Start regtest: simplex regtest
  5. Build: simplex build
  6. Run tests: simplex test
  7. Clean: simplex clean

Reference Repositories

Repository URL
Simplicity (core) https://github.com/BlockstreamResearch/simplicity
SimplicityHL https://github.com/BlockstreamResearch/SimplicityHL
smplx https://github.com/BlockstreamResearch/smplx
simplicity-demo https://github.com/BlockstreamResearch/simplicity-demo
simplicity-contracts https://github.com/BlockstreamResearch/simplicity-contracts
simplicity-codespace https://github.com/Blockstream/simplicity-codespace
simplicityhl-std https://github.com/BlockstreamResearch/simplicityhl-std
simplicityhl-lsp https://github.com/BlockstreamResearch/simplicityhl-lsp
hal-simplicity https://github.com/BlockstreamResearch/hal-simplicity
lwk https://github.com/Blockstream/lwk
ELIPs https://github.com/ElementsProject/ELIPs
elements https://github.com/ElementsProject/elements

Documentation