Laconic state machine
Prathamesh Musale
eb9aa00816
Some checks failed
E2E Tests / test-e2e (push) Failing after 1h21m21s
Integration Tests / test-integration (push) Successful in 2h13m47s
SDK Tests / sdk_tests_authority_auctions (push) Failing after 3h11m11s
SDK Tests / sdk_tests (push) Failing after 3h11m10s
SDK Tests / sdk_tests_nameservice_expiry (push) Failing after 3h11m11s
Unit Tests / test-unit (push) Failing after 3h14m50s
Applications built on laconicd repeatedly pick the Record + attribute-
scan pattern for data that has mutable logical identity (game state,
user profiles, inventories). The query cost then grows linearly with
per-entity version count, and the fix reached for (cache, pagination,
compaction) hides the design mistake rather than correcting it. AI
agents hit this failure mode especially reliably: they pattern-match
the existing client's queryRecords usage as canon and never discover
the Naming API.
This commit adds four pieces of documentation that surface the right
primitive *before* a wrong one is committed to:
* docs/PATTERNS.md — primitive decision tree with concrete
anti-patterns (queryRecords-as-KV, compaction-for-latency,
cache-the-slow-query) and a worked example (mutable game state).
* AGENTS.md — explicit for AI coding agents; names the failure mode,
lists six rules, and tells agents to read PATTERNS.md before
writing their first queryRecords call.
* gql/cerc-io/laconicd/schema.graphql — prescriptive comments on
queryRecords (warning against mutable-identity usage),
getRecordsByIds (point-lookup clarification), and the Naming
API section (USE THIS for current-state lookups).
* README.md — new 'Designing state that lives on laconicd' section
between Usage and Tests, linking both new docs.
|
||
|---|---|---|
| .gitea/workflows | ||
| api/cerc | ||
| app | ||
| cmd/laconicd | ||
| docs | ||
| gql | ||
| proto | ||
| scripts | ||
| tests | ||
| testutil | ||
| utils | ||
| x | ||
| .dockerignore | ||
| .gitignore | ||
| .golangci.yml | ||
| AGENTS.md | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| lockup.md | ||
| Makefile | ||
| README.md | ||
Laconic Network
The Source of Proof. Laconic is a next generation data availability & verifiability layer with cryptographic proofs, powering internet-scale Web3 applications, built on Proof-of-Stake with fast-finality using the Cosmos SDK which runs on top of CometBFT consensus engine.
Installation
Install laconicd:
# install the laconicd binary
make install
Usage
Run with a single node fixture:
# start the chain
./scripts/init.sh
# start the chain with data dir reset
./scripts/init.sh clean
See lockup.md for lockup account usage.
Designing state that lives on laconicd
Before writing a client library, service, or migration that persists data through laconicd, read:
docs/PATTERNS.md— the primitive decision tree. Explains when to use the Naming API (setName/lookupNames/resolveNames) vs. the Record API (setRecord/queryRecords/getRecordsByIds), with worked examples and the common anti-patterns.AGENTS.md— written for AI coding agents, but the failure mode it describes (extending the wrong primitive rather than re-evaluating it) applies to human contributors under deadline pressure too.
Picking the wrong primitive is expensive to unwind: laconicd is append-only, so mistakes persist as on-chain data you cannot silently remove. Spend the 10 minutes to read the pattern guide before the first commit.
Tests
Run tests:
# integration tests
make test-integration
# e2e tests
make test-e2e
Community
The following chat channels and forums are a great spot to ask questions about Laconic: