write-contract

What it does

Guides developers to produce production-quality GenLayer intelligent contracts that pass consensus, handle errors correctly, and survive production. It enforces a pinned GenVM runner version in the first line and prohibits non-versioned or local aliases like py-genlayer:test, py-genlayer:latest, or unversioned runners. It also emphasizes linting with genvm-lint check after writing or modifying a contract. It covers use cases for GenLayer when consensus is needed (dispute resolution, oracle-style markets, compliance, autonomous agents) and requires an architecture boundary note if unclear. It provides a contract skeleton and specific examples for runner dependencies to ensure deterministic, pinned deployment. It details error classification, storage rules, and LLM resilience guidance to ensure validators can independently verify outcomes. It also includes guidance on storage types, layout rules, and how to handle complex state with appropriate GenLayer types and annotations.

How it works

• Begin each contract with a pinned runner version header, e.g. { "Depends": "py-genlayer:..." }, and ensure there is no py-genlayer:test, py-genlayer:latest, or unversioned py-genlayer references.
• Use the provided skeleton demonstrating storage fields, init initialization, and public interfaces for on-chain interactions.
• Pin single-file or multi-file contracts with the appropriate runner section, using the specified formats shown (including py-genlayer-multi for multi-file setups).
• If embeddings or semantic search are used, prepend the appropriate dependencies in a Seq block, combining required runners in the correct order.
• Apply Equivalence Principle logic to determine when to use strict_eq for deterministic calls, or a custom validator function for non-deterministic operations, including an example of a validator pattern with leader_fn and validator_fn.
• Follow the Error Classification and Canonical error handler to distinguish between expected, external, transient, and LLM errors and to route validation accordingly.
• Store state using GenLayer types (TreeMap, DynArray, u256, etc.) and declare storage fields as class-level annotations, with initialization in init only for non-storage fields.
• Use the provided guidance for LLM resilience to defensively parse outputs, and avoid trusting leader outputs alone.

When to use it

• Use GenLayer when the contract must coordinate or settle around a subjective, external, or AI-mediated judgment requiring validator consensus (dispute resolution, oracle-style outcomes, compliance workflows, or auditable settlement).
• Avoid GenLayer when the task is deterministic, entirely off-chain, or can be handled by a deterministic backend, frontend, or non-consensus workflow.

What it can touch

• Mentions allowed tools Bash, Read, Write, Edit, Grep, Glob for implementation workflows; contracts themselves must start with a pinned Depends header and lint with genvm-lint.

Caveats

• The guidance requires strict pinning of runner versions and disallows local aliases; non-deterministic operations should be validated with a custom validator function and possibly non-comparative wrappers if appropriate.
• It prescribes specific storage typing and layout rules and warns about the complexity of cross-chain interop and the need for precise state management.