Prathamesh Musale eb9aa00816 docs: guide agents/humans toward Naming API for mutable logical identity

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.

2026-04-24 16:04:31 +00:00

1.9 KiB

Raw Blame History

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:

1.9 KiB Raw Blame History