Convex-Dev/convex / .claude/skills/convex-lisp
convex-lisp
VerifiedConvex 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.4 KB |
SKILL.md
View on GitHub---
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
- `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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |