Imported from xian-technology/xian-contracting (
AGENTS.md). Install upstream withnpx skills add xian-technology/xian-contracting. Copyright stays with the author.
Repository Guidelines
Scope
xian-contractingowns contract compilation, execution, storage, metering, and runtime security semantics.- Keep node orchestration, genesis distribution, and operator workflow out of this repo.
- This repo is security-sensitive. Favor small, well-tested changes.
Shared Convention
- Follow the shared repo convention in
xian-meta/docs/REPO_CONVENTIONS.md. - Keep this repo aligned with that standard for stable root docs, backlog notes, and folder-level entrypoints.
- Follow the shared change workflow in
xian-meta/docs/CHANGE_WORKFLOW.md. - Before push, review downstream impact on
xian-abci,xian-py, andxian-docs-web, and run the local validation path from this file.
Project Layout
src/contracting/compilation/: parser, compiler, linter, and whitelist logic.src/contracting/execution/: runtime, executor, module loading, and tracing.src/contracting/storage/: drivers, ORM helpers, encoder, and LMDB-backed state storage.src/contracting/contracts/: package-local contract assets such as the built-in submission contract.tests/: unit, integration, security, and performance coverage.
Workflow
mainis the primary working branch for this repo. Stay onmainunless explicitly told otherwise.- Preserve runtime behavior deliberately. If a fix changes execution semantics, add regression tests in the same change.
- Avoid cross-repo orchestration changes here unless the ABCI or CLI layer requires a new importable primitive.
- Keep built-in contracts and storage/runtime helpers aligned with the execution model. Do not treat this repo like a general utilities package.
Validation
- Preferred setup:
uv sync --group dev - Lint:
uv run ruff check . - Format check:
uv run ruff format --check . - Tests:
uv run pytest - If you touch security boundaries or metering, run the relevant
tests/security/andtests/integration/paths explicitly.
Notes
- The test suite now uses a repo-local HOME via
tests/conftest.py, so it does not need host access to~/.cometbft. - Review
examples/and release helpers critically before expanding them; do not add convenience tooling that belongs inxian-cliorxian-stack. - If you touch metering, tracing, imports, or storage encoding, assume the change is consensus-sensitive and test accordingly.
Shared Agent Practices
- Keep changes clean, modular, and professional. Prefer small, cohesive modules, clear naming, explicit boundaries, and tests over quick patches.
- When code behavior, public APIs, user workflows, operator workflows, or configuration semantics change, check whether
../xian-docs-webneeds corresponding documentation updates. If this repo isxian-docs-web, update the relevant published docs in place. Write durable user/developer documentation, not a changelog entry. - Follow
../xian-meta/docs/CODE_GRAPH_WORKFLOW.mdfor graph freshness and source verification. Before relying on graph results, runpython3 ../xian-meta/scripts/graphify_workspace.py status --repo xian-contractingand refresh that repo if stale. - For codebase questions, use the local graph first when
graphify-out/graph.jsonexists: rungraphify query "<question>"; usegraphify affected "<symbol>" --depth 1for direct dependents, larger depths for transitive impact, andgraphify path "<A>" "<B>" --directedfor call paths andgraphify explain "<concept>"for focused concepts. - Dirty
graphify-out/files are expected after hooks or incremental updates and are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. - Use
graphify-out/wiki/index.mdfor broad navigation when it exists. Readgraphify-out/GRAPH_REPORT.mdonly for broad architecture review or when query/path/explain do not surface enough context. - For any non-trivial code change, update the local graph before final verification when
graphify-out/graph.jsonexists. Runpython3 ../xian-meta/scripts/graphify_workspace.py refresh --repo xian-contractingfrom the repo root; use--forceonly for inspected, intentional shrinkage. - After updating the graph, check cross-repo impact before finishing: use
graphify affected, inspect returned source locations, and search affected sibling repos. A missing edge or truncated result does not prove there are no other consumers. - If graphify or dependency analysis shows affected sibling repos, update those repos in the same change when the impact is real and the fix is in scope.
- Treat
graphify-out/as a generated local artifact. Do not commit it.
