--- title: "Convex-Dev/convex" description: "Convex Main Repository - Decentralised platform for the Internet of Value" source: https://github.com/Convex-Dev/convex ref: develop license: null licenseName: "Other" canonical: https://skillsdocs.com/Convex-Dev/convex base: https://github.com/Convex-Dev/convex/blob/develop/ chapters: 20 inlined: 20 withheld: 0 words: 6568 updated: 2026-08-10T23:58:16Z generator: "Skills Docs" --- > **Convex-Dev/convex** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/Convex-Dev/convex > Per-chapter Markdown: https://skillsdocs.com/Convex-Dev/convex/.md > Machine manifest: https://skillsdocs.com/Convex-Dev/convex/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/Convex-Dev/convex > Install: `npx skills add Convex-Dev/convex` > Upstream: https://github.com/Convex-Dev/convex @ `develop` > Licence: Other > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request # Convex-Dev/convex Convex Main Repository - Decentralised platform for the Internet of Value - **Chapters:** 20 - **Inlined:** 20 (licence detected) - **Words:** 6,568 - **Reading time:** 30 min - **Stars:** 117 ## Table of contents 1. [account](https://skillsdocs.com/Convex-Dev/convex/account.md) — Create or inspect Convex accounts. Use when the user wants to set up a new account, check account details, or manage keys. 2. [build-convex](https://skillsdocs.com/Convex-Dev/convex/build-convex.md) — Build the Convex project from source. Use when a contributor wants to compile, test, or package Convex. 3. [cad-reference](https://skillsdocs.com/Convex-Dev/convex/cad-reference.md) — Index of the Convex Architecture Documents (CADs), the normative specifications for Convex. Use to find which CAD governs a subsystem before changing protocol,… 4. [cad3-encoding](https://skillsdocs.com/Convex-Dev/convex/cad3-encoding.md) — CAD3 encoding format — cells, embedded vs branch references, value IDs, validity rules. Use when working on encoders, decoders, serialisation, hashing or anyth… 5. [cns](https://skillsdocs.com/Convex-Dev/convex/cns.md) — Resolve or register Convex Name System (CNS) names. Use when the user wants to look up a CNS name, register a new name, or update a name's target. 6. [convex-db](https://skillsdocs.com/Convex-Dev/convex/convex-db.md) — Use Convex DB — a lattice-backed SQL database. Use when helping users write queries, connect via JDBC or PostgreSQL clients, create tables, insert/query data,… 7. [convex-lisp](https://skillsdocs.com/Convex-Dev/convex/convex-lisp.md) — Convex Lisp language reference — CVM conventions, calling library code, actor definitions, juice and error codes. Use when writing or debugging CVM source for… 8. [deploy](https://skillsdocs.com/Convex-Dev/convex/deploy.md) — Deploy an actor (smart contract) to the Convex network. Use when the user wants to create a new on-chain actor with exported functions. 9. [ecosystem](https://skillsdocs.com/Convex-Dev/convex/ecosystem.md) — Orientation in the Convex ecosystem — what lives in which repository, where the specs and docs are, and which client libraries exist. Use when you need context… 10. [etch](https://skillsdocs.com/Convex-Dev/convex/etch.md) — Inspect and maintain an Etch store — Convex's content-addressed database. Use when examining peer storage, diagnosing corruption, garbage collecting, or readin… 11. [juice](https://skillsdocs.com/Convex-Dev/convex/juice.md) — Juice accounting — the cost of computation and bandwidth on the CVM. Use when reasoning about transaction execution cost, diagnosing a :JUICE failure, or prici… 12. [local-network](https://skillsdocs.com/Convex-Dev/convex/local-network.md) — Run a local Convex test network for development. Use when testing changes against a live network, reproducing a peer issue, or when no remote network is config… 13. [memory](https://skillsdocs.com/Convex-Dev/convex/memory.md) — Memory accounting and allowances — the cost of on-chain storage, and how to minimise and reclaim it. Use when reasoning about state growth, diagnosing a :MEMOR… 14. [peer](https://skillsdocs.com/Convex-Dev/convex/peer.md) — Operate a Convex peer — create, start, list, back up, or instantiate a network genesis. Use when running a peer against a network or setting up a new network. 15. [protocol-versions](https://skillsdocs.com/Convex-Dev/convex/protocol-versions.md) — Protocol versions, migrations and the v1 upgrade — which semantics to write against, and how to change CVM behaviour without forking the network. Use when chan… 16. [query](https://skillsdocs.com/Convex-Dev/convex/query.md) — Execute a read-only CVM query on the Convex network. Use when reading on-chain state, checking balances, looking up accounts, or evaluating Convex Lisp express… 17. [token](https://skillsdocs.com/Convex-Dev/convex/token.md) — Create and manage fungible tokens on Convex. Use when the user wants to create a new token, check token balances, or manage token supply. 18. [transact](https://skillsdocs.com/Convex-Dev/convex/transact.md) — Execute a CVM transaction on the Convex network. Use when the user wants to modify on-chain state, call actor functions, or define values. 19. [transfer](https://skillsdocs.com/Convex-Dev/convex/transfer.md) — Transfer CVM coins or fungible tokens between Convex accounts. Use when the user wants to send coins or tokens to another account. 20. [trust](https://skillsdocs.com/Convex-Dev/convex/trust.md) — Trust monitors — Convex's composable on-chain authorisation model. Use when writing access control, restricting actor functions, defining who may mint or upgra… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/Convex-Dev/convex/blob/develop/._ # Convex - Lattice technology for Open Economic Systems [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) **Convex** is a decentralised network and execution platform. It realises the vision of a true **Stateful Internet**, where the network itself securely hosts, executes, and persists both code and data on a self-sovereign-federated basis. Convex provides a full-stack platform for decentralised applications and programmable economic systems that manage digital assets. Ownership of accounts and assets is cryptographically enforced and can be governed (optionally) through smart contracts. ## Core Technology: Lattice-Based Architecture Unlike traditional blockchains, Convex is built on **Lattice Technology**, which leverages the mathematical properties of lattices to deliver superior consensus and verifiability. This foundation yields significant advantages over conventional blockchain designs: | Feature | Convex Advantage | |----------------------------------------------|-----------------------------------------------------------------------------------| | **Global State Model** | Single, consistent global state with immutable data structures and atomic transactions | | **Virtual Machine** | Lambda-calculus-based VM supporting fully Turing-complete smart contracts | | **Throughput** | Tens of thousands of write TPS today; designed to scale to millions in the future | | **Networking** | Simple, robust random-gossip protocol | | **Confirmation Latency** | Millisecond-range global consensus (network-speed dependent) | | **Energy Efficiency** | **100% Green** – powered by Convergent Proof-of-Stake (no energy-intensive mining) | | **Programming Language** | Integrated on-chain compiler for **Convex Lisp** (a modern, secure Lisp dialect) | ## Why Convex? - **Developer-friendly**: Write smart contracts in a powerful, functional Lisp that compiles and executes directly on-chain. - **Instant finality**: Transactions confirm in milliseconds with cryptographic guarantees. - **Truly scalable**: Lattice agreement eliminates the bottlenecks of linear blockchains. - **Sustainable by design**: Minimal energy footprint while maintaining full decentralisation and security. Convex is the high-performance, eco-friendly backbone for the next generation of decentralised finance, agentic economies, self-sovereign ownership, and beyond. ## About this repository This repository contains the core Convex distribution including: - The Convex Virtual Machine (CVM) including data structures and execution environment - The standard Convex Peer server implementation (NIO based) implementing Convergent Proof of Stake (CPoS) for consensus - CLI Tools for operating Peers, scripting transactions and more - The Etch database for persistent data storage - SQL database layer with JDBC driver and PostgreSQL wire protocol server - A Swing GUI for managing local peers / exploring the network - A simple REST API server - JMH Benchmarking suite - Java Client API The repository also contains core "on-chain" libraries providing key full-stack functionality and tools for decentralised applications, including: - `convex.fungible` - Fungible Tokens - `asset.nft.simple` - Basic lightweight Non-fungible tokens - `convex.asset` - library for managing arbitrary digital assets using a common abstraction - `convex.trust` - library for access control and trusted operations - `torus.exchange` - decentralised exchange for trading fungible tokens and currencies - Example code and templates for various forms of smart contracts ## Modules | Name | Description | Maven | Javadoc | | ----- | ----------- | ----- | ------- | | [convex-core](https://github.com/Convex-Dev/convex/tree/develop/convex-core/) | CVM, data structures and consensus | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-core.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-core/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-core) | | [convex-peer](https://github.com/Convex-Dev/convex/tree/develop/convex-peer/) | Peer implementation and networking | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-peer.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-peer/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-peer) | | [convex-cli](https://github.com/Convex-Dev/convex/tree/develop/convex-cli/) | Command Line Tools | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-cli.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-cli/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-cli) | | [convex-gui](https://github.com/Convex-Dev/convex/tree/develop/convex-gui/) | Convex Desktop GUI Interface | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-gui.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-gui/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-gui) | | [convex-db](https://github.com/Convex-Dev/convex/tree/develop/convex-db/) | SQL database with JDBC and PostgreSQL protocol | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-db.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-db/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-db) | | [convex-x402](https://github.com/Convex-Dev/convex/tree/develop/convex-x402/) | x402 payment protocol support | [![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-x402.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex) | [![javadoc](https://javadoc.io/badge2/world.convex/convex-x402/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-x402) | For local use of Convex data structures and CVM execution, `convex-core` is typically sufficient. To run a peer or communicate with one over the network, include `convex-peer` as a dependency. Other modules are designed primarily as standalone applications or client libraries. ## Key features * *Convex Virtual Machine (CVM)* - Secure, Lambda Calculus-based environment for smart contracts and autonomous agents. * *Decentralised Consensus* - Tamper-proof and censorship-resistant via Convergent Proof of Stake (CPoS). * *Performance and Scalability* - Processes tens of thousands (and sometimes up to millions) of transactions per second with sub-second global consensus. * *Eco-Friendly* - Minimal energy consumption with CPoS, ensuring a sustainable platform. ## Getting Started ### Your first transaction (no install) The fastest way to try Convex is the **[Web Sandbox](https://convex.world/sandbox)** — a live REPL on the public testnet. Evaluate an expression, then deploy and call a one-line smart contract: ```clojure ;; Free query — no account needed (+ 1 2 3) ;; => 6 ;; With a faucet-funded account, deploy and call an actor (a smart contract) (deploy '(defn ^:callable greet [name] (str "Hello, " name "!"))) ;; => #1234 ;; your new actor's address (call #1234 (greet "world")) ;; => "Hello, world!" ``` Want the full walkthrough — including the TypeScript, Python, and Java SDKs against the testnet? See the **[Quick Start guide](https://docs.convex.world/docs/tutorial/quickstart)**. ### Prerequisites - Java 21+ ([Download Temurin](https://adoptium.net/temurin/releases/?version=21)) — JDK 25 recommended ### Quick Install **macOS / Linux:** ```bash curl -fsSL https://convex.world/install.sh | bash ``` **Windows (PowerShell):** ```powershell irm https://convex.world/install.ps1 | iex ``` This installs `convex.jar` and adds a `convex` command to your PATH. ### Other options **Download directly:** - [Latest stable release](https://github.com/Convex-Dev/convex/releases/latest/download/convex.jar) - [Snapshot build](https://github.com/Convex-Dev/convex/releases/tag/snapshot-develop) (develop branch, may be unstable) **Docker:** ```bash docker pull convexlive/convex:latest docker run convexlive/convex peer start ``` **Build from source:** ```bash git clone https://github.com/Convex-Dev/convex.git cd convex mvn clean install ``` ### Running Convex Try Convex Lisp straight from the terminal — no network, keys or setup needed: ```bash convex eval "(+ 1 2)" # => 3 convex repl # interactive REPL on an ephemeral local instance ``` Both commands run against any network too, e.g. `convex repl --host localhost`. Launch the desktop GUI: ```bash convex desktop ``` Start a local peer test network with GUI: ```bash convex local gui ``` See all available commands: ```bash convex --help ``` ## Examples - **Convex Lisp** — runnable `.cvx` demos in [`convex-core/src/test/resources/examples`](https://github.com/Convex-Dev/convex/blob/develop/convex-core/src/test/resources/examples): fungible tokens, assets, trust monitors, the Torus DEX, and `language.cvx` for the language itself. - **Java** — using the CVM and data structures directly in [`convex-core/src/test/java/convex/core/examples`](https://github.com/Convex-Dev/convex/blob/develop/convex-core/src/test/java/convex/core/examples) (start with `RawCVM.java`). - **Recipes & SDK quickstarts** — task-oriented guides at [docs.convex.world/docs/tutorial/recipes](https://docs.convex.world/docs/tutorial/recipes) and the per-language [client SDK quickstarts](https://docs.convex.world/docs/tutorial/client-sdks). ## Contributing Contributions are welcome under the Convex Public License. Contributors retain copyright but must accept the license terms. A Contributors Agreement is required for all submissions to the core repository. The Convex Foundation may award Convex Coins to contributors for significant ecosystem contributions. These native utility tokens enable network service access and may be exchangeable for other digital assets. See [CONTRIBUTING.md](https://github.com/Convex-Dev/convex/blob/develop/CONTRIBUTING.md) to get started, [BUILD.md](https://github.com/Convex-Dev/convex/blob/develop/BUILD.md) for build and release detail, and [AGENTS.md](https://github.com/Convex-Dev/convex/blob/develop/AGENTS.md) for the conventions any coding agent working in this repository should follow. ## Community We use Discord as for discussing Convex - you can join the public server at [https://discord.com/invite/xfYGq4CT7v](https://discord.com/invite/xfYGq4CT7v) Alternatively, email: info(at)convex.world ## Copyright Copyright 2017-2026 The Convex Foundation and Contributors Unless otherwise specified, source code is available under the terms of the [Convex Public License](https://github.com/Convex-Dev/convex/blob/develop/LICENSE.md) --- ## 1. account - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/account/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/account/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/account.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: account description: Create or inspect Convex accounts. Use when the user wants to set up a new account, check account details, or manage keys. argument-hint: "[create|info|keys] [address]" --- # Convex Account Management Accounts are self-sovereign: an address like `#1337` controlled by a key pair. See the `convex-lisp` skill for CVM conventions. ## Via the CLI Always available from a built `convex.jar`: ```bash java -jar convex.jar account create # create an account java -jar convex.jar account info #13 # full account record java -jar convex.jar account balance #13 # coin balance java -jar convex.jar account fund #13 # fund from the faucet, where available java -jar convex.jar key generate # new key pair in the keystore java -jar convex.jar key list # keys in the keystore java -jar convex.jar key import|export|delete|sign ``` `--keystore` and `--storepass` select the keystore; `-k`/`--key` and `-p`/`--keypass` select a key within it. Add `--host`/`--port` to target a specific network. ## Via a Convex MCP Server If one is configured (tool names look like `mcp____…`) — it is set up per user, not by this repository, so check before relying on it: - **Create in one step:** `signingCreateAccount` — key pair plus on-chain account, optionally funded from the faucet - **From a raw key:** `keyGen`, then `createAccount` with the public key - **Inspect:** `describeAccount` (full record), `getBalance` (balance only) - **Keys:** `signingListKeys`, `signingListAccounts`, `signingCreateKey` ## Via Query `(account #ADDR)` returns the full account record; `(balance #ADDR)` the coin balance. Both are free — see the `query` skill. ## Handling Keys **Save the seed when an account is created — it cannot be recovered.** Tell the user explicitly at the moment of creation, not afterwards. Never write a seed or passphrase into a file in the repository, a commit message, or any output that will be shared onward. If the user pastes one, use it for the operation at hand and do not repeat it back. ## Display - Balances in CVM units (1 CVM = 10^9 copper) - Addresses with the `#` prefix - Public keys as hex strings --- ## 2. build-convex - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/build-convex/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/build-convex/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/build-convex.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: build-convex description: Build the Convex project from source. Use when a contributor wants to compile, test, or package Convex. disable-model-invocation: true allowed-tools: Bash argument-hint: "[module] [--test]" --- # Build Convex Build the Convex Maven project. Requires Java 21+ (JDK 25 recommended) and Maven 3.7+. Run every command from the repository root — that is already the working directory, so do not `cd` anywhere first. Use `./mvnw` in preference to `mvn` when the wrapper is present, so the build uses the pinned Maven version. Parse `$ARGUMENTS` for two things: - a **module** name (any argument starting `convex-`), e.g. `convex-core` - the **`--test`** flag ## Full build, skipping tests The default when no arguments are given: ```bash ./mvnw -B clean install -DskipTests ``` ## Build a single module ```bash ./mvnw -B clean install -DskipTests -pl -am ``` `-am` also builds the modules that one depends on. ## Build with tests When `--test` is present, or the user asks for tests, drop `-DskipTests`. This matches what CI runs, so it is the command to use before claiming work is done: ```bash ./mvnw -B clean install ``` For a single module's tests: ```bash ./mvnw -B test -pl -am ``` Report the result — success or failure — and any errors, concisely. On failure, quote the first real compilation or test error rather than the Maven summary. --- ## 3. cad-reference - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/cad-reference/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/cad-reference/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/cad-reference.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: cad-reference description: Index of the Convex Architecture Documents (CADs), the normative specifications for Convex. Use to find which CAD governs a subsystem before changing protocol, encoding, consensus or economic behaviour. --- # Convex Architecture Documents CADs are the **normative specifications** for Convex. Where the code and a CAD disagree, that is a bug in one of them — not a licence to pick either. Before changing behaviour in a specified area, read the governing CAD and say which one you relied on. **Read them at `https://docs.convex.world/docs/cad/`** — the slug is the CAD directory name without its numeric prefix, e.g. CAD003 is `https://docs.convex.world/docs/cad/encoding`. If the `design` repository is checked out alongside this one, the sources are in `design/docs/cad/_/index.md`. Do not assume it is present. ## Core Protocol | CAD | Slug | Covers | |-----|------|--------| | 000 | `principles` | Design principles behind every other decision | | 001 | `arch` | Overall architecture | | 002 | `values` | CVM values | | 003 | `encoding` | **CAD3 encoding format** — see the `cad3-encoding` skill | | 004 | `accounts` | Accounts, addresses, controllers | | 005 | `cvmex` | CVM execution model | | 033 | `cvmtypes` | CVM type system | ## Resources and Economics | CAD | Slug | Covers | |-----|------|--------| | 006 | `memory` | **Memory accounting and allowances** — see the `memory` skill | | 007 | `juice` | **Juice accounting and pricing** — see the `juice` skill | | 020 | `tokenomics` | Coin supply, distribution, denominations | | 016 | `peerstake` | Peer staking | ## Language and Compilation | CAD | Slug | Covers | |-----|------|--------| | 008 | `compiler` | Compiler | | 009 | `expanders` | Expanders and macros | | 011 | `errors` | Error handling and error codes | | 012 | `numerics` | Numeric semantics | | 013 | `metadata` | Metadata | | 026 | `lisp` | Convex Lisp | | 032 | `reader` | CVX reader syntax | ## Transactions and Consensus | CAD | Slug | Covers | |-----|------|--------| | 010 | `transactions` | Transaction format and lifecycle | | 015 | `peercomms` | Peer communication protocol | | 017 | `peerops` | Peer operations | | 018 | `scheduler` | Scheduled execution | | 021 | `observability` | Observability | | 027 | `log` | Event logging | ## Storage and Lattice | CAD | Slug | Covers | |-----|------|--------| | 047 | `etch` | Etch storage format — see the `etch` skill | | 024 | `data_lattice` | Data lattice | | 035 | `cursors` | Lattice cursors | | 036 | `lattice_node` | Lattice node | | 037 | `kv_database` | KV database | | 039 | `convex_sql` | Convex SQL — see the `convex-db` skill | | 040 | `lattice_queue` | Lattice queue | | 028 | `dlfs` | Data Lattice File System | | 044 | `json` | JSON on the lattice | | 045 | `lattice_apps` | Lattice applications | | 046 | `cell_explorer` | Cell explorer | ## Assets, Identity and Trust | CAD | Slug | Covers | |-----|------|--------| | 019 | `assets` | Asset model | | 029 | `fungible` | Fungible token standard — see the `token` skill | | 031 | `nft_metadata` | NFT metadata | | 030 | `torus` | Torus DEX | | 022 | `trustmon` | **Trust monitors** — the authorisation model; see the `trust` skill | | 014 | `cns` | Convex Name System — see the `cns` skill | | 034 | `curated_registry` | Curated registry | | 023 | `keystore` | Keystore | | 025 | `wallet` | HD wallets | | 038 | `lattice_auth` | Lattice authentication | | 043 | `did` | Decentralised identity | ## Integration | CAD | Slug | Covers | |-----|------|--------| | 041 | `mcp` | Model Context Protocol | | 042 | `x402` | x402 protocol | CAD `0000cads` is the index and describes the CAD process itself. --- ## 4. cad3-encoding - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/cad3-encoding/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/cad3-encoding/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/cad3-encoding.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: cad3-encoding description: CAD3 encoding format — cells, embedded vs branch references, value IDs, validity rules. Use when working on encoders, decoders, serialisation, hashing or anything that reads or writes cell encodings. --- # CAD3 Encoding CAD3 is the byte-level encoding for all Convex data. Normative spec: `https://docs.convex.world/docs/cad/encoding`. Read it before changing encoder or decoder behaviour — this skill is orientation, not a substitute. ## The Model A **cell** is the unit of encoding. Cells reference other cells, forming a Merkle DAG: every reference carries the hash of the referenced encoding. - **Encoding is a byte sequence.** Every cell maps to exactly one encoding, and distinct cells map to distinct encodings. Both directions matter — the round-trip and the uniqueness. - **Value ID** = SHA3-256 of the encoding. This is the content address. - **Maximum encoding length is 16383 bytes**, so any cell fits a fixed buffer and most operations stay O(1). - The first byte is the **tag**, which determines how the rest is read. A tag not defined in CAD3 MUST be rejected. ## Embedded vs Branch The distinction drives both correctness and performance. - **Embedded**: the child's encoding sits inside the parent's encoding. An embedded cell MUST be 140 bytes or less. - **Branch**: the child is referenced externally by value ID, and must be fetched separately. A cell that is embedded MUST NOT also be referenced externally. Allowing both would give a parent two valid encodings, breaking uniqueness. When you touch embedding rules, that invariant is what you are protecting. Embedding is why `[1 2 3 4 5]` is one encoding rather than six, and why embedded values cost zero memory — see the `memory` skill. ## Validity An encoding is valid if some cell produces exactly those bytes. Implementations MUST reject: - trailing bytes after a complete valid encoding - a sequence that ends before the encoding is complete - undefined or reserved tags Random bytes are almost always invalid, which is what lets a peer discard corrupt or hostile input cheaply. Preserve that property — it is load-bearing for the peer's robustness against malicious messages. ## Traps **Do not "fix" the decoder to reject non-canonical `NaN`.** Every 64-bit pattern in a Double is a valid encoding, including every distinct `NaN` payload, both signed zeroes, infinities and subnormals. Each is a *distinct value* with its own value ID. The CVM defines one canonical `NaN` (`##NaN`, `0x1d7ff8000000000000`) and normalises results to it, but that is a **CVM value-layer concern enforced by coercion** — never by rejecting an encoding. This looks like a decoder bug and is not one. Contrast with Integers, where excess leading bytes are genuinely *redundant* and therefore invalid. The test is whether two byte sequences would denote the same value: if so, only one may be legal. **Preserve values you do not understand.** CAD3 is deliberately extensible — applications assign their own meaning to values, particularly in the `0xAn`, `0xCn`, `0xDn` and `0xEn` categories. An implementation MUST relay encoded values it cannot interpret rather than dropping or normalising them. **Value IDs of non-branch cells may not be in storage.** Only roots and branches are generally persisted. If you hold a value ID for an intermediate cell, navigate down from a known root instead of assuming a store lookup will resolve it. ## Where the Code Lives Encoding logic is in `convex-core`: see `convex.core.cvm.CVMEncoder`, `CVMTag`, and `convex-core/docs/ENCODER_DESIGN.md`. Changes here affect consensus compatibility. `SnapshotStateTest` replays a fixed state and checks its hash — **if your change moves that hash, it is a consensus-visible change**, not a refactor, and needs to be gated on a protocol version rather than shipped unconditionally. --- ## 5. cns - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/cns/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/cns/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/cns.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: cns description: Resolve or register Convex Name System (CNS) names. Use when the user wants to look up a CNS name, register a new name, or update a name's target. argument-hint: "[resolve|register|update] " --- # Convex Name System (CNS) CNS maps human-readable names (like `convex.fungible`) to on-chain addresses. See the `convex-lisp` skill for CVM conventions. ## Resolve a Name In CVM source, `@convex.fungible` resolves the name directly — this is the normal way to reach a library. To inspect a name's record (value, controller, metadata, child node), use a Convex MCP server's `resolveCNS` tool if one is configured. Otherwise query it: ```bash java -jar convex.jar client query '@convex.fungible' ``` ## Register or Update a Name The registry actor is `#9`, available in CVM code as `*registry*`. It has no `cns-update` function — use `create` for a new name and `update` for an existing one: ```clojure ;; Create a new name pointing at a target, with *address* as controller (*registry*/create 'my.name #TARGET *address*) ;; Update an existing name you control (*registry*/update 'my.name #NEW-TARGET) ;; Change who controls a name (*registry*/change-control 'my.name #NEW-CONTROLLER) ``` These are transactions (they change state). Notes: - **Creating requires controlling the parent namespace.** `(*registry*/create 'my.name ...)` needs the `my` node to exist and to trust you — otherwise it fails with `:TRUST` "Forbidden to create CNS node". Top-level names require special authority. - `create` also accepts optional controller, metadata and child arguments: `(*registry*/create 'my.name target controller metadata)`. - Note `(*registry*/register {:name "..."})` is unrelated — it registers metadata for the *caller's own account*, not a CNS name. ## CNS in Code - `@convex.fungible` in CVM source resolves to the actor address at runtime - Use CNS paths instead of hardcoded addresses for portable code - `(@convex.fungible/balance #TOKEN #USER)` calls `balance` on the resolved actor ## Common CNS Names | Name | Purpose | |------|---------| | `convex.fungible` | Fungible token standard library | | `convex.trust` | Trust and access control | | `convex.asset` | Generic asset interface | | `asset.nft.simple` | Non-fungible token standard | | `asset.multi-token` | Multi-token standard | (Resolve with `(*registry*/resolve 'name)` to get the current address — these are network-specific.) --- ## 6. convex-db - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/convex-db/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/convex-db/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/convex-db.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: convex-db description: Use Convex DB — a lattice-backed SQL database. Use when helping users write queries, connect via JDBC or PostgreSQL clients, create tables, insert/query data, or use the direct lattice API. argument-hint: "[query|connect|create|example]" --- # Using Convex DB Convex DB provides SQL access over lattice data. Connect via JDBC, PostgreSQL wire protocol, or the direct lattice API. **Reference:** `convex-db/README.md` for full documentation including replication, PostgreSQL server setup, and architecture details. ## Connecting ### JDBC (Java) ```java // In-memory Connection conn = DriverManager.getConnection("jdbc:convex:mydb"); // Persistent (Etch-backed, survives restarts) Connection conn = DriverManager.getConnection("jdbc:convex:file:/data/mydb.etch"); ``` Driver auto-registers via ServiceLoader. Class: `convex.db.jdbc.ConvexDriver` ### PostgreSQL Clients (psql, DBeaver, DataGrip, Python, etc.) ```bash # Start the PG server java -cp convex-db.jar convex.db.psql.PgServer -p 5432 -d mydb # Then connect with any PG client psql -h localhost -p 5432 -d mydb ``` ```python import psycopg2 conn = psycopg2.connect(host="localhost", port=5432, dbname="mydb") ``` ## Creating Tables ```sql CREATE TABLE users (id, name, email) ``` Column 0 (first column) is always the primary key. Types are inferred from inserted data. ## Inserting Data ```sql INSERT INTO users VALUES (1, 'Alice', 'alice@example.com') ``` For bulk loading, use prepared statements with batch: ```java PreparedStatement ps = conn.prepareStatement("INSERT INTO users VALUES (?, ?, ?)"); for (int i = 0; i < 10000; i++) { ps.setLong(1, i); ps.setString(2, "Name-" + i); ps.setString(3, "email-" + i + "@example.com"); ps.addBatch(); } ps.executeBatch(); ``` ## Querying ```sql -- Point lookup (fast — O(log n) via PK index pushdown) SELECT * FROM users WHERE id = 1 -- Filtering, sorting, pagination SELECT name, email FROM users WHERE name LIKE 'A%' ORDER BY name LIMIT 10 -- Joins SELECT c.name, o.amount FROM customers c INNER JOIN orders o ON c.id = o.customer_id -- Aggregations SELECT department, COUNT(*), AVG(salary) FROM employees GROUP BY department HAVING COUNT(*) > 5 ``` ### Supported SQL - **DDL:** `CREATE TABLE`, `DROP TABLE` - **DML:** `INSERT`, `UPDATE`, `DELETE` - **Queries:** `SELECT`, `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET` - **Joins:** `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `CROSS JOIN` - **Aggregations:** `GROUP BY`, `HAVING`, `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` - **Expressions:** `CASE WHEN`, `COALESCE`, `CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL` - **Functions:** `ABS`, `FLOOR`, `CEIL`, `SQRT`, `UPPER`, `LOWER`, `TRIM`, `SUBSTRING`, `LENGTH`, `CONCAT` ## Transactions ```java conn.setAutoCommit(false); stmt.execute("INSERT INTO users VALUES (2, 'Bob', 'bob@example.com')"); stmt.execute("UPDATE users SET email = 'new@example.com' WHERE id = 1"); conn.commit(); // atomic merge — all changes become visible // or conn.rollback() to discard ``` ## Column Types | SQL Type | CVM Type | Notes | |----------|----------|-------| | BIGINT / INTEGER | CVMLong | 64-bit signed integer | | DOUBLE | CVMDouble | 64-bit float | | VARCHAR | AString | Unicode string | | BOOLEAN | CVMBool | true/false | | VARBINARY / BLOB | ABlob | Binary data | | TIMESTAMP | CVMLong | Milliseconds since epoch | | ANY | ACell | Dynamic type | ## Direct Lattice API For programmatic access without SQL overhead: ```java ConvexDB cdb = ConvexDB.create(); SQLDatabase db = cdb.database("mydb"); // Create table db.tables().createTable("users", new String[]{"id", "name", "email"}); // Insert db.tables().insert("users", 1, "Alice", "alice@example.com"); // Point lookup AVector row = db.tables().selectByKey("users", 1); // Scan all Index> all = db.tables().selectAll("users"); // Delete db.tables().deleteByKey("users", 1); ``` ## Performance Tips - **Use PK lookups** (`WHERE id = ?`) for point queries — O(log n) via index pushdown - **Use PreparedStatements** — plans compile once, reuse across executions - **Use batch inserts** for bulk loading — significantly faster than individual statements - **Full scans** are O(n) — filter on PK when possible ## Building and Testing Run from the repository root — see the `build-convex` skill. ```bash # Build (-am also builds convex-core, which this depends on) ./mvnw -B clean install -DskipTests -pl convex-db -am # Run tests ./mvnw -B test -pl convex-db -am ``` --- ## 7. convex-lisp - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/convex-lisp/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/convex-lisp/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/convex-lisp.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: convex-lisp description: Convex Lisp language reference — CVM conventions, calling library code, actor definitions, juice and error codes. Use when writing or debugging CVM source for queries, transactions or actors. --- # Convex Lisp Shared conventions for all CVM source. The `query`, `transact`, `deploy`, `token` and `transfer` skills assume what is written here. ## Units and Notation - Coin amounts are in **copper**. 1 CVM coin = 1,000,000,000 copper (10^9). Convert for display: report "1.5 CVM", not "1500000000". - Account addresses take a `#` prefix: `#13`, `#1337`. - CNS names take an `@` prefix when resolved in source: `@convex.fungible`. ## Calling Library Code Resolve libraries through CNS rather than hardcoding addresses: ```clojure (@convex.fungible/balance #128 #13) ``` This is the idiom used throughout the codebase — match it. A `let`-bound address also works (`(let [f @convex.fungible] (f/balance …))`) and is occasionally tidier for repeated calls, but is rare in practice. **Never use `import` in query or transaction source.** It mutates the account environment and costs extra juice on every transaction that carries it. Use the `@name/fn` form instead. Library and actor *bodies* are different: they are deployed once, so an `import` at the top of a `.cvx` library resolves once and is idiomatic — the core libraries do it, for instance `convex/trust/monitors.cvx`. Do not "fix" those. ## Actors Actors are on-chain accounts with their own address, balance and state. ```clojure (deploy '(do (def counter 0) (defn ^:callable increment [] (set! counter (+ counter 1)) counter))) ``` - **`^:callable` is the only export mechanism.** There is no `export` form. The map form `^{:callable true}` is equivalent and equally common in the core libraries. - `def`s in the actor body that are not `^:callable` are private state. Update them from inside with `set!`. - `deploy` returns the new address. `deploy` also accepts a **vector** of code forms, which is how library builders are composed: `(deploy [(build-token …) (add-mint …)])`. - `(set-controller #ADDR)` sets who may upgrade the actor. ## Juice and Memory Transactions consume juice, paid in copper by the origin account, and consume memory allowance if they grow the state. Queries are free — they execute against current state and are discarded, so prefer a query whenever you only need to read. See the `juice` skill for execution costs and `memory` for storage — including how to minimise and reclaim on-chain storage, which is worth reading before designing an actor that stores anything. ## Error Codes Errors surface as keywords. The ones you will actually hit: | Code | Meaning | |------|---------| | `:UNDECLARED` | Symbol does not exist — usually a wrong function name | | `:CAST` | Wrong type passed to a function | | `:ARGUMENT` | Right type, invalid value | | `:ARITY` | Wrong number of arguments | | `:STATE` | Operation invalid for current state (e.g. missing callable) | | `:TRUST` | Caller lacks rights for the operation | | `:FUNDS` | Insufficient coin balance | | `:JUICE` | Ran out of juice — transaction too expensive | | `:MEMORY` | Insufficient memory allowance | | `:NOBODY` | Target account does not exist | | `:COMPILE` | Source did not compile | `:UNDECLARED` on a library call almost always means the function name is wrong. Check the library source in `convex-core/src/main/cvx/` rather than guessing — several plausible names (`quantity`, `supply`) do not exist. ## Protocol Version Write against **protocol version 1** semantics — see the `protocol-versions` skill. Several core behaviours are fixed there rather than at genesis, so a network still at version 0 differs: - `update` and `update-in` drop an argument in their variadic (5+ arg) arities - quasiquote of a set or map containing an unquote yields a call form, `~false` does not unquote, `define` evaluates its value twice, and `call` with too many arguments silently does nothing If you hit one of these, it is a known genesis bug fixed by v1 — not something to work around in new code. --- ## 8. deploy - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/deploy/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/deploy/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/deploy.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: deploy description: Deploy an actor (smart contract) to the Convex network. Use when the user wants to create a new on-chain actor with exported functions. argument-hint: "" --- # Deploy a Convex Actor Actors are autonomous on-chain programs with their own address, state, and callable functions. See the `convex-lisp` skill for CVM conventions and error codes. Deploying is a transaction, so it needs a key the user has supplied — see `transact`. ## Actor Structure A typical actor deployment: ```clojure (deploy '(do ;; Internal state (private to the actor) (def counter 0) ;; Callable functions: mark each with ^:callable so it can be ;; invoked from outside the actor via (call ...) (defn ^:callable increment [] (set! counter (+ counter 1)) counter) (defn ^:callable get-count [] counter))) ``` ## Key Rules - `deploy` returns the new actor's address (e.g. `#12345`) - Only functions tagged with `^:callable` metadata can be called from outside (there is no `export` form). The equivalent map form is `^{:callable true}` - Use `set!` to update an existing `def` from inside a function; plain `def`s declared in the actor body are private state - Actors have their own `*address*` and `*balance*` - Use `(set-controller #ADDR)` inside the actor to set who can upgrade it - `deploy` also accepts a **vector** of code forms, which is how library builders are composed into one actor: `(deploy [(@convex.fungible/build-token {…}) (@convex.fungible/add-mint {…})])` ## After Deployment 1. Note the returned address for the user 2. Optionally register a CNS name: `(call #9 (cns-update 'my.actor.name *address*))` 3. Test by calling a `^:callable` function: `(call #NEW-ADDR (get-count))` ## Workflow 1. Help the user design the actor based on `$ARGUMENTS` 2. Write the Convex Lisp source 3. Deploy using `transact` with the `(deploy ...)` expression 4. Verify the deployment with a test query --- ## 9. ecosystem - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/ecosystem/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/ecosystem/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/ecosystem.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: ecosystem description: Orientation in the Convex ecosystem — what lives in which repository, where the specs and docs are, and which client libraries exist. Use when you need context that is not in this repository. --- # The Convex Ecosystem Convex is a lattice-based decentralised network and execution platform. Data merges like CRDTs rather than forming a linear chain, consensus is Convergent Proof of Stake (CPoS), and the CVM is a lambda-calculus virtual machine for functional smart contracts. This repository (`Convex-Dev/convex`) is the reference implementation. Several things an agent needs are deliberately **not** here. ## Where Things Live | What | Where | |------|-------| | Reference implementation — CVM, consensus, peer, CLI, tooling | `Convex-Dev/convex` (this repo) | | **CADs** — normative specifications | `Convex-Dev/design`, under `docs/cad/` | | Glossary and tutorials | `Convex-Dev/design`, under `docs/tutorial/` | | Rendered docs | `https://docs.convex.world` | The `design` repository is the authority on *what Convex should do*; this repository is *what it currently does*. When they disagree, one of them has a bug — see the `cad-reference` skill for how to find the governing CAD. Do not assume `design` is checked out locally. Use `https://docs.convex.world` unless you have confirmed the repository is present alongside this one. ## Module Map The 13 Maven modules are listed in `AGENTS.md` with their purposes, and each has its own `README.md`. In short: `convex-core` holds the CVM, consensus and Etch; `convex-peer` the networking; `convex-cli`, `convex-gui` and `convex-restapi` the interfaces; `convex-p2p` bundles the node server. ## Client Libraries | Language | Repository | |----------|-----------| | Java | `convex-java` module in this repo | | Clojure | `Convex-Dev/convex.cljc` | | TypeScript | `Convex-Dev/convex.ts` | | Python | `Convex-Dev/convex-api-py` | Prefer the in-repo `convex-java` module for JVM integration — it is versioned with the network implementation. ## Networks - **Protonet** (production): `peer.convex.live` - Testnets are used for tooling and experimentation; the endpoint in use is recorded in `AGENTS.md` under Network Defaults. Anything you deploy to Protonet is real. Confirm the target network before any transaction, and prefer a local network for development — see the `local-network` skill. ## Terminology Convex has its own vocabulary and it is **not** interchangeable with blockchain terminology. Never substitute "gas", "fees", "blockchain", "chain", "miner", "validator", "block", "wei", "satoshi" or "mainnet". Use: CVM coin, Copper, Juice, Peer, Actor, Lattice, CPoS, Belief, Etch, CAD, CNS, Protonet. The canonical glossary is at `https://docs.convex.world/docs/tutorial/glossary` — check it rather than guessing at a translation. ## Related Projects The ecosystem page at `https://docs.convex.world` lists community projects, wallets, demos and integrations. Treat that list as the current source; entries here would go stale. --- ## 10. etch - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/etch/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/etch/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/etch.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: etch description: Inspect and maintain an Etch store — Convex's content-addressed database. Use when examining peer storage, diagnosing corruption, garbage collecting, or reading data by hash. allowed-tools: Bash argument-hint: "[info|validate|dump|read|gc|migrate|repair] " --- # Etch Store Operations Etch is Convex's content-addressed store: values are keyed by hash, and a single root hash reaches everything retained. Peers keep their state here. Every subcommand takes the store file with `-e` / `--etch`: ```bash java -jar convex.jar etch info -e /path/to/store.etch ``` ## Inspecting | Command | Purpose | |---------|---------| | `etch info` | Summary of the database — start here | | `etch validate` | Check store integrity; `-m/--max-failures N` to bound reporting | | `etch dump` | Export contents, CSV by default (value ID, type, memory size, encoding) | | `etch read ...` | Read specific values by hash; `--limit N` to cap output | `info`, `dump` and `read` take `-o` / `--output-file` to write to a file rather than the terminal — use it for `dump` on any real store, which is large. Start a diagnosis with `info`, then `validate`. If validation reports failures, capture the output before doing anything that mutates the store. ## Maintenance These **modify or destroy data**. Confirm with the user, and make sure the peer using the store is stopped first — operating on a live store risks corruption. | Command | Effect | |---------|--------| | `etch gc` | Garbage collect: retains the root and everything reachable, discards the rest | | `etch clear` | Clears the root data. Does *not* collect garbage | | `etch migrate --into ` | Copy everything into another store; `--set-root` to set the destination root | | `etch repair --into ` | Reconstruct a fresh store from independently validated cells; source unchanged | | `etch recover` | Adopt a completed GC cutover and roll forward — for a store interrupted mid-GC | | `etch write -c/--cvx ` | Write a CVM value into the store | `migrate` is the safe way to compact or relocate: it leaves the source intact, so prefer it to `gc` when the store matters and disk allows. `repair` is the offline salvage path for a dirty or damaged source. It holds an exclusive source lock, scans through physical EOF, and writes only canonical CAD3 values whose stored content hashes verify. A complete result requires both a fully persisted selected root and an exhaustive scan. If either condition fails, the command reports failure but may leave a valid partial destination; never replace the source with that output automatically. Recovering an interrupted GC is what `recover` is for — reach for it before concluding a store is lost. --- ## 11. juice - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/juice/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/juice/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/juice.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: juice description: Juice accounting — the cost of computation and bandwidth on the CVM. Use when reasoning about transaction execution cost, diagnosing a :JUICE failure, or pricing a new CVM operation. --- # Juice Accounting Juice prices **computation and bandwidth**. It is a flow: consumed and paid per transaction, never held. Storage is priced separately — see the `memory` skill. Normative spec: `https://docs.convex.world/docs/cad/juice`. ## The Calculation ``` Juice Fees = Juice Consumed × Juice Price Juice Consumed = Transaction Size Cost + Σ(cost of each operation executed) Transaction Size Cost = TRANSACTION_PER_BYTE × storage size of the transaction ``` `TRANSACTION_PER_BYTE` is 20, so **the size of the submitted transaction is itself a cost**, independent of what it does. Compact transaction source is cheaper source. ## Allowance Every transaction carries a **juice allowance**: - Specified by the user, or the maximum available if unspecified - Capped at **10,000,000**, bounding the cost of any single transaction - May not exceed what the origin account can actually pay **On a `:JUICE` failure the origin is charged the full allowance and every state change is rolled back.** Running out is not free — it is the most expensive way for a transaction to fail. When execution cost is uncertain, estimate against a local network before submitting. ## Price Juice price lives in the CVM state and is readable from CVM code as `*juice-price*`. It moves with network load: - Rises when sustained load exceeds `JUICE_PER_SECOND` (100,000,000) - Decays towards its floor when load is lighter — roughly a six-second half life at zero load - Has a hard minimum of **1**; juice is never free The genesis price is 2 and the scale factor is 1.125. Governance may update the scale factor and throughput constant. This is the cryptoeconomic defence: sustaining an attack means paying exponentially rising prices, and a burst while prices are low can only delay confirmation, not exclude legitimate transactions. ## Pricing New Operations If you add a CVM op or runtime function, it needs a juice cost. - Every op MUST have a **fixed positive** cost — nothing executes free. - An op whose work scales with input size MUST have a cost that scales too. - The CVM MUST check sufficient juice **before** performing O(n) work, and raise `:JUICE` if it is not there. That ordering is a security property, not an optimisation. If an attacker can trigger O(n) work having committed less than O(n) of juice, the asymmetry is a denial-of-service vector. Cost should track an upper bound on compute time, storage size or bandwidth — whichever dominates. ## Relationship to Memory A transaction short of memory allowance can buy memory from the pool using its **remaining juice** — so juice exhaustion can surface as a `:MEMORY` failure and vice versa. See the `memory` skill for that interaction. --- ## 12. local-network - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/local-network/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/local-network/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/local-network.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: local-network description: Run a local Convex test network for development. Use when testing changes against a live network, reproducing a peer issue, or when no remote network is configured. allowed-tools: Bash argument-hint: "[--count N] [--gui]" --- # Run a Local Convex Network A local network is the default way to exercise changes in this repository. It needs no credentials, no remote host, and can be thrown away and recreated freely. Prefer it over a remote network for anything that is not specifically about remote behaviour. Requires a built `convex.jar` — see the `build-convex` skill. ## Start a Temporary Network ```bash java -jar convex.jar local start ``` Starts a throwaway test network. State is not preserved between runs, which is what you want for testing. Useful options: | Option | Effect | |--------|--------| | `--count N` | Number of peers to launch | | `--ports ...` | Specific peer ports (default: assigned automatically) | | `--api-port N` | Port for the REST API | | `--norest` | Do not start the REST server | | `--no-tray` | No system tray icon | | `--protocol-version N` | Pin the protocol version | ## Start with the Peer Manager GUI ```bash java -jar convex.jar local gui ``` Launches the same local network under the peer manager GUI — useful for watching consensus and inspecting peer state visually. ## Talking to It Once running, point the client commands at the local peer: ```bash java -jar convex.jar client query --host localhost --port '(balance #12)' java -jar convex.jar client status --host localhost --port ``` ## Notes for Tests Do **not** start a network from a JUnit test by shelling out to the CLI. Tests construct peers in-process; see the existing tests in `convex-peer`. The rules in `AGENTS.md` apply — bind port `0` and read back the assigned port, and wait on real signals rather than sleeping. Stop the network when finished — it holds ports and a temporary store. --- ## 13. memory - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/memory/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/memory/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/memory.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: memory description: Memory accounting and allowances — the cost of on-chain storage, and how to minimise and reclaim it. Use when reasoning about state growth, diagnosing a :MEMORY failure, or designing actors that store data. --- # Memory Accounting Memory prices **storage**. Unlike juice, it is a stock: held as an allowance, consumed when state grows, and **refunded when state shrinks**. Computation is priced separately — see the `juice` skill. On-chain storage is potentially permanent, and every peer bears it. Memory accounting exists so that whoever creates that burden accounts for it. Normative spec: `https://docs.convex.world/docs/cad/memory`. ## Storage Size ``` storage size = 64 + (bytes of the cell's own encoding) + (memory size of child cells) ``` Two consequences worth internalising: - **The 64-byte constant is per non-embedded cell.** Cell *count* costs, not just bytes. A structure split across many small cells is far more expensive than the same data embedded. - **Embedded cells have a memory size of zero.** Their bytes are already inside the parent's encoding. Embedding is genuinely free storage — see the `cad3-encoding` skill for the 140-byte embedding limit. ## Consumption Measured per transaction, at the end: ``` Memory Consumption = state size at end − state size at start ``` When consumption is positive, resolved in this order: 1. Deduct from the user's **memory allowance**, if sufficient. 2. Otherwise **buy from the memory pool**, paying at most `remaining juice × juice price`. This is where memory and juice meet — a transaction can fail for memory because it spent its juice elsewhere. 3. Otherwise fail with **`:MEMORY`**, roll back all state changes, and still charge the juice. When consumption is **negative, the allowance is refunded** by the amount released. Freeing storage pays. ## Minimise Allocation Treat on-chain storage as the scarcest thing you are spending. In order of leverage: - **Embed rather than branch.** Small values inside a parent encoding cost nothing extra; each separate cell costs 64 bytes of overhead before its content. - **Keep cell counts low.** Prefer one compact structure over many small ones. - **Store the minimum that satisfies the requirement.** Derive what can be derived, and keep off-chain what does not need consensus. Storing a hash or a reference is usually enough when the payload itself need not be on-chain. - **Do not store what a query can compute.** On-chain caching of derived values trades permanent storage for transient compute — usually the wrong way round. - **Actors should allocate sparingly when called by users.** The *caller* pays for what your actor allocates, so a wasteful actor makes every interaction with it expensive. This is a competitive property, not just good manners. Note that de-duplication does not help the allocating user: identical encodings are stored once network-wide, but you still pay allowance for what you allocate. Do not design around it. ## Reclaim Aggressively Every byte released is allowance refunded, so cleaning up is directly rewarded — for users and actors alike. - **Delete data you no longer need.** Definitions in your own account environment are yours to remove, and safe to remove if you hold backups — the data can always be restored later. - **Give actors clean-up functions.** A well-designed actor lets participants remove what is finished with: read messages, filled orders, zero-balance holder records, expired offers, de-registrations. Without such a function the storage is stranded permanently. - **Expect callers to use them.** The party who cleans up claims the refund, so clean-up paths get used. That is the intended incentive — a responder can come out ahead by tidying up after an interaction. - **Give actors a way to reclaim their own allowance.** Actors hold allowances but normally do not spend them: the transaction *origin* pays. The exception is **scheduled execution**, where the actor is itself the origin. An allowance that accumulates in an actor with no reclaim path is unreachable forever, and cannot be retrofitted without an upgrade. Allowances may also be transferred directly between accounts, which is how actors and multi-account users manage them without allocate/deallocate tricks. ## The Memory Pool An automated market maker. Seeded at genesis with 1,000,000 bytes against 1,000 Convex Coins (~1 Coin/KB), and grown at a fixed rate (currently 1 MB per day). Growth is deliberate: it avoids a hard supply ceiling and penalises hoarding, since new supply dilutes accumulated allowances. ## Implementation Notes Memory size is computed lazily and **cached per cell**; peers MUST cache it to meet performance requirements. Cells are immutable, so a cached size is never invalidated — that is what keeps accounting O(1) per allocated cell. The accounting subsystem is designed to cause **no net cell allocations itself**, so it cannot drive the state growth it exists to control. Preserve that if you change it: update embedded fields on existing cells rather than allocating new ones. --- ## 14. peer - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/peer/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/peer/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/peer.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: peer description: Operate a Convex peer — create, start, list, back up, or instantiate a network genesis. Use when running a peer against a network or setting up a new network. allowed-tools: Bash argument-hint: "[create|start|list|backup|genesis]" --- # Running a Convex Peer A peer participates in consensus (CPoS), holds state in an Etch store, and optionally serves the REST API. For local development and testing you almost always want the `local-network` skill instead — it starts a throwaway network in one command. Use this skill when running a peer against a real network, or setting up a new one. `peer` accepts `-c` / `--config` for a configuration file. ## Joining an Existing Network ```bash java -jar convex.jar peer create --host ``` Configures and creates a peer against a running network. Needs an existing peer to bootstrap from and a valid peer controller account; generates a new peer key unless one is supplied. Then start it: ```bash java -jar convex.jar peer start ``` Useful `start` options: | Option | Effect | |--------|--------| | `--peer-port N` | Port for the peer protocol | | `--api-port N` | Port for the REST API | | `--url` / `--base-url` | Externally visible URL for this peer | | `-a`, `--address` | Peer controller account | | `--genesis` | Start from a genesis state | | `--reset` | Reset stored state before starting | | `--recalc` | Recalculate state from a given block position | | `--norest` | Do not start the REST server | | `--no-tray` | No system tray icon | | `--protocol-version N` | Pin the protocol version | `--reset` discards local peer state. Confirm before using it on anything that is not disposable. ## Creating a New Network ```bash java -jar convex.jar peer genesis ``` Instantiates a new Convex network — a genesis state with this peer as the first participant. `--governance-key` sets the governance key; `--protocol-version` pins the protocol version. This creates a *new network*, not a connection to an existing one. Do not run it when the intent was to join Protonet or a testnet. ## Managing ```bash java -jar convex.jar peer list # peers in the current store java -jar convex.jar peer backup -o # back up stored peer data ``` Back up before any operation that resets or migrates peer state. See the `etch` skill for working on the underlying store directly. ## Keys Peer keys are separate from account keys: `--peer-key` and `--peer-keypass` select the peer's key from the keystore. The peer controller account is set with `-a` / `--address`. --- ## 15. protocol-versions - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/protocol-versions/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/protocol-versions/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/protocol-versions.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: protocol-versions description: Protocol versions, migrations and the v1 upgrade — which semantics to write against, and how to change CVM behaviour without forking the network. Use when changing core functions, juice costs, encodings or on-chain libraries. --- # Protocol Versions and Migrations The **protocol version** is the count of upgrades applied to a network, starting at `0` at genesis. Genesis is immutable — it is the network's identity — so every change to CVM semantics after launch arrives as a scheduled migration that increments the version by exactly 1. Full design: `convex-core/docs/UPGRADE.md`. Read it before authoring a migration; this skill is orientation and conventions. ## Write Against v1 **v1 is the target.** It is the first upgrade, it bundles every bug known at genesis, and it is what networks will be running. Unless you are specifically reasoning about live or historical behaviour, v1 semantics are the semantics. This is the project's own test convention — three state roles, each answering a different question: | Role | Version | Use | |------|---------|-----| | **Target** — `InitTest.UPGRADED` / `BaseTest.UPGRADED` | `MAX_VERSION` | **The `ACVMTest` default.** Libraries, actors and CVM behaviour are tested against where the network is going. | | **LIVE** — `InitTest.LIVE` / `BaseTest.LIVE` | `Migrations.LIVE_VERSION` | The release gate: what live peers run today, so a release does not break them before they upgrade. | | **Genesis** — `InitTest.STATE` / `BaseTest.STATE` | `0` | Pinned where genesis is the point: genesis-hash invariants, replay (`SnapshotStateTest`), and intended-diff contrast tests (`MigrationFixesTest`). | `Migrations.LIVE_VERSION` is bumped **when, and only when, the live network applies an upgrade**. Everything pinned to LIVE follows automatically. ## What v1 Contains The bootstrap (installing `schedule-upgrade` / `unschedule-upgrade`) plus fixes that could not ship any other way, because a naive fix would move the genesis hash: | Migration | Fixes | |-----------|-------| | `v1-core.cvx` | `update` / `update-in` variadic arities (#533); quasiquote of sets/maps, `~false`, `define` double-evaluation, `call` arity (#598) | | `v1-trust.cvx` | `trusted?` now fails closed against defective monitors (#623) | | `v1-fungible.cvx` | `add-mint` `:max-supply` defaults to unlimited rather than 0 (#528) | | `v1-asset.cvx`, `v1-box.cvx`, `v1-delegate.cvx`, `v1-metadata.cvx`, `v1-multi-token.cvx`, `v1-nft-basic.cvx`, `v1-nft-simple.cvx` | library fixes (#600, #620, #621, #622, #623) | Two of these change behaviour agents rely on — see the `trust` and `token` skills, which document the v1 behaviour and flag the pre-v1 trap. ## Changing CVM Behaviour Where the change lives determines the strategy. **Tier 1 — state-resident core.** Functions defined in `core.cvx` are compiled into account `#8` at genesis; they are *state*. Fix by migration: replace the binding with the recompiled definition. No Java version branch. Caveat: the compiler statically links core symbols, so already-deployed actors keep the old embedded function unless the migration also sweeps environments. Whether to sweep is a per-upgrade decision. **Tier 2 — native semantics.** Opcodes, native core functions, juice costs and cast rules are the transition function, in Java. These change by version-keyed dispatch: ```java long cost = (state.getProtocolVersion() >= 3) ? Juice.NEW_COST : Juice.OLD_COST; ``` **Whether a gate is needed is decided by replay evidence, not judgement.** Make the change unconditional locally and run `SnapshotStateTest`: if the replay hash moves, recorded history exercised the old semantics and the gate is mandatory; if not, it ships unconditionally with no permanent branch. Branches are permanent — replay from genesis needs every historical semantics. **Tier 3 — encodings.** Decoding happens outside any state context, so it **cannot** branch on version. Decoders stay permissive of all historical forms forever; the version gates what the CVM *writes and canonicalises*. See the `cad3-encoding` skill — this is why a permissive decoder is correct rather than a bug. ## Authoring a Migration - **Purity is a hard contract.** A migration is `State → State` with no clock, randomness or I/O. An impure migration forks the network. - **The list is append-only forever.** Position is identity — `Migrations.get(k)` produces version `k+1` — so never insert or reorder. - **Test the exact delta.** Every migration needs tests asserting precisely what changed *and* that nothing else did (compare untouched subtrees by hash). - Failure at an activation boundary makes peers **withdraw** from consensus rather than produce a state — a stall is recoverable, divergence is not. `MigrationFixesTest` owns the intended differences between genesis and upgraded semantics; add to it when a migration changes observable behaviour. ## Fresh Networks Launchers that create a new genesis (`local start`, `peer genesis`, `peer start --genesis`, GUI local networks) apply all migrations at creation, so a **fresh network starts at `MAX_VERSION`** — it has no history to preserve and should not launch with known-fixed bugs. Pin a lower version with `--protocol-version` (CLI) or `:protocol-version` (peer config) to mirror a network that has not yet upgraded. This is how you reproduce live behaviour locally while v1 is pending. --- ## 16. query - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/query/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/query/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/query.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: query description: Execute a read-only CVM query on the Convex network. Use when reading on-chain state, checking balances, looking up accounts, or evaluating Convex Lisp expressions. argument-hint: " [address]" --- # Query Convex State Queries are read-only, free and instant. They never modify state and need no key, so prefer a query over a transaction whenever you only need to read. **Expression:** `$0` **Address (optional):** `$1` — the account context for the query (e.g. `#13`) See the `convex-lisp` skill for CVM conventions and error codes. ## How to Run It **With a Convex MCP server configured** (tool names look like `mcp____query`), use its `query` tool. The server is configured per user, not by this repository — do not assume it is present. **Otherwise use the CLI**, which always works from a built `convex.jar`: ```bash java -jar convex.jar client query '(balance #13)' java -jar convex.jar client query --host --port '(balance #13)' java -jar convex.jar client query -a #13 '*balance*' ``` `-a` / `--address` sets the account context. Against a local network started with the `local-network` skill, pass `--host localhost --port `. ## Common Queries | Task | Expression | |------|-----------| | Coin balance | `(balance #13)` | | Own balance | `*balance*` | | Account info | `(account #13)` | | Token balance | `(@convex.fungible/balance #TOKEN #USER)` | | Token supply | `(@convex.fungible/total-supply #TOKEN)` | | Lookup symbol | `(lookup #ADDR 'symbol)` | | Full state | `*state*` (large!) | `lookup` needs a literal symbol as its last argument — it is resolved at compile time, so a computed symbol fails with `:COMPILE`. Present balances in CVM units (e.g. "1.5 CVM", not "1500000000 copper"). --- ## 17. token - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/token/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/token/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/token.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: token description: Create and manage fungible tokens on Convex. Use when the user wants to create a new token, check token balances, or manage token supply. argument-hint: "[create|balance|mint|transfer] [args...]" --- # Fungible Tokens on Convex Fungible tokens use the `@convex.fungible` standard library (`convex-core/src/main/cvx/convex/asset/fungible.cvx`). See the `convex-lisp` skill for CVM conventions, and `transact` for how transactions are signed. ## Create a New Token **Fixed supply** — no further tokens can ever be minted: ```clojure (deploy (@convex.fungible/build-token {:supply 1000000})) ``` **Mintable** — `build-token` alone provides *no* mint or burn capability. To allow minting you must compose `add-mint` into the same deployment: ```clojure (deploy [(@convex.fungible/build-token {:supply 1000000}) (@convex.fungible/add-mint {:minter *address* :max-supply 1000000000})]) ``` Decide which the user wants before deploying — the choice is permanent, and a token deployed without `add-mint` fails on any later mint attempt. `build-token` config: `:supply` (defaults to 0), `:initial-holder` (defaults to `*address*`), `:decimals`. `add-mint` config: `:minter` (any trust monitor, defaults to `*address*`) and `:max-supply` (from protocol v1, defaults to unlimited). **Always set `:max-supply` explicitly.** Before v1 activates, omitting it defaults the cap to `0` — and because `0` is truthy in CVM, that installs a zero cap which blocks *all* minting, silently producing a mintable-looking token that can never mint (#528). Setting it explicitly is correct under both genesis and v1. See the `protocol-versions` skill. `deploy` returns the token's actor address. ## Operations | Task | Source | |------|--------| | Check balance | `(@convex.fungible/balance #TOKEN #HOLDER)` | | Total supply | `(@convex.fungible/total-supply #TOKEN)` | | Decimals | `(@convex.fungible/decimals #TOKEN)` | | Transfer | `(@convex.fungible/transfer #TOKEN #DEST AMOUNT)` | | Mint | `(@convex.fungible/mint #TOKEN AMOUNT)` | | Burn | `(@convex.fungible/burn #TOKEN AMOUNT)` | There is no `quantity` function — it returns `:UNDECLARED`. Total supply is `total-supply`. `balance`, `total-supply` and `decimals` are reads: use a query, not a transaction. `transfer`, `mint` and `burn` change state and must be transactions. If a Convex MCP server is configured, its `getBalance` and `transfer` tools also accept a `token` parameter. ## Authorisation Minting requires the caller to satisfy the token's `:minter` trust monitor; anything else fails with `:TRUST`. `:minter` takes any trust monitor, not just an address — see the `trust` skill for composing them (a mint window, a multi-party whitelist, delegated revocation). Creating, transferring, minting and burning are all transactions, so they need a key the user has supplied — see the `transact` skill. Without one you can prepare the source but not execute it. --- ## 18. transact - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/transact/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/transact/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/transact.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: transact description: Execute a CVM transaction on the Convex network. Use when the user wants to modify on-chain state, call actor functions, or define values. argument-hint: "" --- # Execute a Convex Transaction Transactions modify global state atomically. They consume juice, paid in copper by the origin account, and must be signed. **Source:** `$ARGUMENTS` See the `convex-lisp` skill for CVM conventions and error codes. ## Authorisation A transaction requires a key. You have one only if the user has supplied it — a signing-service passphrase, or a raw seed. There is no ambient authority here, so: 1. **User has a key in the signing service** — use the MCP `signingTransact` tool with their address and passphrase. 2. **User has a raw seed** — use the MCP `transact` tool with address and seed. 3. **Neither** — you cannot execute. Use `prepare` to build the unsigned transaction, or the CLI below, and hand it back for the user to sign. Do not treat case 3 as a blocker to work around. Preparing the transaction and returning it is the correct outcome. ## Via the CLI Works from a built `convex.jar` and needs no MCP server: ```bash java -jar convex.jar client transact -a #13 '(def my-var 42)' java -jar convex.jar client transact -a #13 -k -p '(transfer #42 1000000000)' ``` `-k` / `--key` selects the key from the keystore and `-p` / `--keypass` is its passphrase; `--keystore` and `--storepass` select the keystore itself. Add `--host` / `--port` for a non-default network. ## Common Patterns | Task | Source | |------|--------| | Transfer coins | `(transfer #DEST AMOUNT)` | | Define a value | `(def my-var 42)` | | Call an actor | `(call #ACTOR (function-name arg1 arg2))` | | Call a library | `(@convex.fungible/transfer #TOKEN #DEST AMOUNT)` | | Set controller | `(set-controller #ADDR)` | Confirm source, destination and amount with the user before executing anything that moves value or changes account control. State what will happen in CVM units, not copper. --- ## 19. transfer - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/transfer/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/transfer/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/transfer.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: transfer description: Transfer CVM coins or fungible tokens between Convex accounts. Use when the user wants to send coins or tokens to another account. argument-hint: " [token-address]" --- # Transfer Coins or Tokens A transfer is a transaction, so it needs a key the user has supplied — see the `transact` skill for the authorisation model and the CLI form. Without a key you can prepare the transfer but not execute it. ## CVM Coin Transfer Source: `(transfer #42 1000000000)` — sends 1 CVM. With a Convex MCP server configured, its `transfer` tool takes **to** (destination address) and **amount** (in copper). ## Fungible Token Transfer Source: `(@convex.fungible/transfer #TOKEN #DEST AMOUNT)` With the MCP `transfer` tool, set the `token` parameter to the token actor address. ## Before Executing - **Confirm destination and amount with the user.** Restate both in CVM units — "send 2.5 CVM to #42" — and get agreement before signing. A transfer is irreversible. - **Convert to copper**: multiply CVM by 1,000,000,000. Getting this wrong by a factor of 10^9 is the easiest and most expensive mistake here. - **Check the sender's balance first** with a query, so a `:FUNDS` failure is caught before signing rather than after. - For tokens, check the *token* balance, not the coin balance — they are unrelated. Report the result in CVM units (e.g. "Sent 2.5 CVM to #42"). --- ## 20. trust - **Source:** https://github.com/Convex-Dev/convex/blob/develop/.claude/skills/trust/SKILL.md - **Raw:** https://raw.githubusercontent.com/Convex-Dev/convex/develop/.claude/skills/trust/SKILL.md - **Markdown:** https://skillsdocs.com/Convex-Dev/convex/trust.md - **Licence:** Other — https://github.com/Convex-Dev/convex --- name: trust description: Trust monitors — Convex's composable on-chain authorisation model. Use when writing access control, restricting actor functions, defining who may mint or upgrade, or reviewing authorisation logic. --- # Trust Monitors Trust monitors are Convex's authorisation primitive: composable, sandboxed, on-chain modules that grant or deny access. Anywhere an actor asks "may this caller do this?", the answer should come from a trust monitor rather than hand-rolled logic. Normative spec: `https://docs.convex.world/docs/cad/trustmon`. Reference implementation: `convex-core/src/main/cvx/convex/core/trust.cvx` and `convex/trust/monitors.cvx`. ## The Model Every check is a triple: - **Subject** — who is acting, almost always an account, usually `*caller*` - **Action** — what they are doing, a short keyword such as `:update` - **Object** — what they are acting on, typically an address or ID This is the reference monitor model. Keeping the triple explicit is what makes monitors reusable across unrelated contracts. ## Referencing a Monitor A monitor reference is an account address, optionally **scoped**: ```clojure #45 ;; an account [#78 1467476] ;; a scoped account — same actor, different rule nil ;; never authorises anything ``` `nil` is a valid monitor that always denies — useful as a safe default. A bare address trusts only itself: `(trusted? #13 #13)` is `true`, anything else `false`. That makes "the owner" expressible without deploying anything. ## Checking Trust ```clojure (@convex.trust/trusted? monitor subject) (@convex.trust/trusted? monitor subject action) (@convex.trust/trusted? monitor subject action object) ``` Omitted action and object are passed as `nil`. Inside an actor, the usual shape is: ```clojure (when-not (trust/trusted? minter *caller* :mint) (fail :TRUST "No rights to mint")) ``` Use `:TRUST` for authorisation failures — that is what callers expect. ## Fail Closed A monitor MUST return `true` or `false`, but a defective or malicious one may throw or return something else. A checker MUST treat any error or non-`true` result as **denial**, and must not let it propagate — an error-propagating checker is itself a denial-of-service vector, since an actor holding an attacker-supplied monitor would throw on every check. `trusted?` implements this from **protocol version 1**: the monitor call is wrapped in `query` against re-entrancy, errors are caught as `false`, and the result is `boolean`-coerced. Write against that behaviour — it is the target semantics, and `MigrationFixesTest` pins it. ```clojure ;; what trusted? does from v1 (boolean (try (query (call monitor (check-trusted? subject action object))) false)) ``` **Before v1 activates**, the genesis `trusted?` in `core/trust.cvx` keeps the `query` guard but does *not* catch the error or coerce the result — so a defective monitor can throw through it, or grant on a truthy non-boolean. If you are deploying an actor that accepts **caller-supplied** monitors onto a network still at version 0, apply the wrapper yourself. For monitors you control, the plain call is fine either way. See the `protocol-versions` skill. ## Writing a Monitor Implement `check-trusted?` as a callable taking exactly three arguments: ```clojure (defn ^:callable check-trusted? [subject action object] (boolean (and (= subject object) (= action :examine-self)))) ``` Requirements that are not optional: - **No side effects.** A monitor MUST work correctly inside `query`, because callers wrap it in one to block re-entrancy. - **Return a strict boolean** for every possible argument combination. - **Be O(1)** in computation and stack depth, with a small constant. Use pre-computed sets and maps for lookups. - **Never scan arbitrary data structures.** An unbounded scan inside a monitor is a denial-of-service vector, since the monitor runs on every check. ## Standard Monitors `convex.trust.monitors` provides composable monitors that need **no deployment** — each returns a scoped address evaluated inline. | Constructor | Grants when | |-------------|-------------| | `(mon/permit-subjects #3 #14)` | subject is in the set | | `(mon/permit-actions :open :close)` | action is in the set | | `(mon/all m1 m2 …)` | every listed monitor grants | | `(mon/any m1 m2 …)` | any listed monitor grants | | `(mon/everyone)` | always | | `(mon/before end)` / `(mon/after start)` / `(mon/between start end)` | within the timestamp window | | `(mon/rule (fn [s a o] …))` | the function returns truthy | | `(mon/owns asset)` | subject owns the asset | | `(mon/delegate allow deny base)` | `deny` first, then `allow`, else `base` | Compose rather than write bespoke logic: ```clojure (@convex.trust.monitors/all (@convex.trust.monitors/permit-subjects #13 #17) (@convex.trust.monitors/permit-actions :open :close)) ``` `delegate` checks **deny before allow**, which is the ordering you want for revocation. ## Guidance **Hard-code actions.** An action keyword SHOULD NOT come from, or be influenced by, untrusted input — otherwise a caller can select which authorisation branch to be checked against. Keep actions literal at the call site. **Keep actions simple.** They may be any CVM value, but complex action structures make security bugs easy. A keyword is almost always right. **Let users supply the monitor.** The point of the pluggable design is that whoever controls a resource chooses its access rules. Take a monitor reference as configuration rather than baking a whitelist into an actor — this is exactly how `add-mint` takes `:minter`; see the `token` skill. **Related libraries:** `convex.trust.whitelist`, `convex.trust.ownership-monitor`, `convex.trust.delegate` and `convex.trust.governance`.