Skip to content

Convex-Dev/convex / .claude/skills/convex-lisp

convex-lisp

Verified

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:

(@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.

(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.
  • defs 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:

CodeMeaning
:UNDECLAREDSymbol does not exist — usually a wrong function name
:CASTWrong type passed to a function
:ARGUMENTRight type, invalid value
:ARITYWrong number of arguments
:STATEOperation invalid for current state (e.g. missing callable)
:TRUSTCaller lacks rights for the operation
:FUNDSInsufficient coin balance
:JUICERan out of juice — transaction too expensive
:MEMORYInsufficient memory allowance
:NOBODYTarget account does not exist
:COMPILESource 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
  • dotimes, for, for-loop and switch can capture user variables in their expansions (#602) — v1 rebinds them hygienically
  • gensym, cat and splice do not exist (:UNDECLARED), and char? fails :CAST rather than :UNDECLARED — it is installed but version-gated, so do not read its pre-v1 failure as a missing function

If you hit one of these, it is a known genesis gap fixed by v1 — not something to work around in new code.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall