forked from cerc-io/laconicd
Prathamesh Musale
eb9aa00816
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.
70 lines
1.9 KiB
Markdown
70 lines
1.9 KiB
Markdown
<div align="center">
|
|
<h1> Laconic Network </h1>
|
|
</div>
|
|
|
|
|
|
|
|
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](https://github.com/cosmos/cosmos-sdk/) which runs on top of [CometBFT](https://github.com/cometbft/cometbft) consensus engine.
|
|
|
|
## Installation
|
|
|
|
Install `laconicd`:
|
|
|
|
```bash
|
|
# install the laconicd binary
|
|
make install
|
|
```
|
|
|
|
## Usage
|
|
|
|
Run with a single node fixture:
|
|
|
|
```bash
|
|
# start the chain
|
|
./scripts/init.sh
|
|
|
|
# start the chain with data dir reset
|
|
./scripts/init.sh clean
|
|
```
|
|
|
|
See [lockup.md](./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`](./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`](./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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
- [Laconic Twitter](https://twitter.com/laconicnetwork)
|
|
- [Website](https://laconic.com)
|