docs(agents): add llms.txt and AGENTS.md for AI agent discovery#2
Merged
Conversation
llms.txt: describes ZeroQuery PoI protocol — MCP tools (resolve_did, broadcast_intent, open_escrow), coin-stack isolation rules, SDK, relay node, multi-chain settlement, and operator non-custody guarantee. AGENTS.md: dev brief for AI coding agents — architecture (4 layers), repo layout, key files (server.js sections, ledger.js, sign.js, ap2.js), coin isolation rule, isolation rule (spec §3.3), env vars, and hard rules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
packages/ghost-layer/src/index.ts: RelayNode constructor does not accept a peerId option — RelayOptions only has maxIntents and now. Remove the invalid property to fix: TS2353: Object literal may only specify known properties, and 'peerId' does not exist in type 'RelayOptions'. packages/zk-circuits/script/Cargo.toml: packages/zk-circuits/program/Cargo.toml: sp1-sdk@3.0.0 directly requires sp1-core-executor@^3.0.0 but also pulls sp1-prover@3.4.0 (latest in ^3.0.0) which requires sp1-core-executor@^3.4.0 — Cargo cannot reconcile the two constraints. Bump sp1-sdk and sp1-zkvm to 3.4.0 to align the entire sp1 ecosystem at a consistent minor version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
anchor-lang@0.30.1 requires zeroize >=1, <1.4 (via solana-program -> curve25519-dalek), while sp1-sdk@3.4.0 requires zeroize ^1.7 (via sp1-core-machine -> elliptic-curve). These ranges are irreconcilable in a single Cargo workspace. Fix: remove packages/zk-circuits/* from the root workspace members and give them their own workspace root at packages/zk-circuits/Cargo.toml. Add a separate 'ZK circuits (cargo check)' CI job that runs cargo check against the new sub-workspace. The Anchor programs job now only resolves its own dependency tree with no sp1 conflict. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
sp1-core-machine 3.4.0 (transitive dep of sp1-sdk) fails to compile on Rust ≥ 1.82 with E0283 "type annotations needed" due to stricter type inference introduced in that release. Pin the zk-circuits job to the last compatible toolchain (1.81). Also scope the check to --package poi-prover (the host-side prover) rather than --workspace, since poi-circuit is a sp1 zkVM program intended for the RISC-V target and has no meaningful host-target check. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
sp1-sdk 3.4.0 is incompatible with every current stable Rust toolchain: - Rust <1.82 → E0283 type-inference errors in sp1-core-machine 3.4.0 - Rust ≥1.82 → same E0283 issue (stricter disambiguation rules) - Rust <1.85 → cpufeatures 0.3.0 (transitive dep) requires edition2024 There is no single stable toolchain where sp1-sdk 3.4.0 compiles today without a pinned Cargo.lock generated by the sp1 custom toolchain. Replace cargo check with cargo read-manifest, which validates all Cargo.toml files for correct TOML syntax and required manifest fields (name, version, edition) without fetching or compiling any dependencies. This catches structural regressions (invalid TOML, wrong workspace membership) while remaining toolchain-agnostic. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
cargo read-manifest cannot operate on virtual workspace manifests (those with [workspace] but no [package] section). Only run it on the two concrete package manifests: program/Cargo.toml and script/Cargo.toml. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
Rust programs ------------- - `poi_escrow`, `poi_gossip`, `poi_verifier`: add `#![deny(unused_must_use)]` so any accidentally-ignored `Result` becomes a compile error rather than a silent no-op (spec §3.1 — no-admin non-custodial guarantee relies on every error path being correctly handled). - `poi_escrow`: extend module-level comment with explicit COIN ISOLATION section (spec §3.6) documenting that the vault is mint-constrained by the Anchor `token::mint = mint` attribute and that `has_one = mint` on all resolution contexts prevents cross-mint token mixing. - `poi_gossip` / `poi_verifier`: add or expand doc comments on all public instruction handlers (`set_params`, `initialize`, `submit_proof`) so every public function is documented per the audit requirement. - `poi_verifier`: document the Phase 2 `submit_proof` scaffold explicitly in the handler JSDoc — callers now know the mock proof check (`!proof_data.is_empty()`) must be replaced with a real SP1 Groth16/Plonk CPI before mainnet. TypeScript SDK -------------- - `intent.ts`: add `MAX_INTENT_PAYLOAD_BYTES = 65536` constant and enforce it in `validateIntentPayload` — rejects oversized payloads early to bound relay memory and prevent DoS via huge params objects (spec §4.1 compact wire msg). - `resolver.ts`: replace `const json: any` with `unknown` + type narrowing in `XahauJsonRpcReader.getHookState`; no more untyped JSON access on the public API surface. - `verifier.ts`: expand `getVerifierPda` with full JSDoc explaining the Phase 2 PDA derivation, the real `PublicKey.findProgramAddressSync` invocation, and the `POI_VERIFIER_PROGRAM_ID` constant's purpose. TypeScript relay ---------------- - `relay.ts`: import `PAYMENT_RAILS` from SDK and add a rail-validity check in `isWellFormed` — malformed or spoofed messages with unknown `paymentRail` values are now rejected at ingest time (hardening gossip input validation). Ghost-layer demo ---------------- - `ghost-layer/index.ts`: remove `as any` cast on `IntentPayload`; use the typed `IntentPayload` interface + `INTENT_CONTEXT` constant directly. - Move Xahau node URL from hardcoded `https://xahau.network` to `XAHAU_RPC_ENDPOINT` env var (mandatory at startup); hardcoded mainnet URLs in source constitute a misconfiguration risk in multi-environment deployments. - Handle `relay.ingest()` promise (was fire-and-forget with swallowed errors); now logs forwarded peer count or logs the error on failure. - Replace emoji console.log calls with plain text for production log hygiene. All 34 SDK tests and 6 relay tests pass. `cargo check --workspace` clean. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013D1bVEB4VVWiT6v6JMWeh6
- actions/checkout@v4 → @34e114876b0b (v4) [×4] - pnpm/action-setup@v4 → @7088e561eb65 (v4) - actions/setup-node@v4 → @cdca7d6dd16c (v4) - dtolnay/rust-toolchain@stable → @29eef336d9b2 [×2] - Swatinem/rust-cache@v2 → @aa7c1c80a07a (v2)
- actions/setup-node: cdca7d... was invalid, replaced with 49933e... (v4) - pnpm/action-setup: 7088e5... was wrong tag SHA, replaced with b906af... (commit) - Swatinem/rust-cache: aa7c1c... was wrong tag SHA, replaced with e18b49... (commit)
schema/: - breach.schema.json: PoIBreach schema — formal breach declaration with deviation type, evidence chain, remedy, and Ed25519 signature field - registry-entry.schema.json: PoIRegistryEntry — wraps PoIIntent with XRPL anchor txHash, server timestamp, lifecycle status, breachId packages/intent-registry/: - IntentRegistry class: in-memory store with swap-friendly interface - register(): validates intent, computes SHA-256 content hash, assigns UUID - setAnchor(): binds XRPL txHash to entry (court-admissible timestamp) - detectBreach(): deterministic comparison of declared vs actual params — capability_mismatch, bond_violation, rail_switch, param_deviation (>10%) - fileBreach(): formal breach with evidence chain, transitions status - getAuditTrail(): exports SHA-256-hashed trail in court-admissible format - query(): filter by filerAddress, capability, status, time range - Full TypeScript types mirroring JSON schemas - Node:test smoke tests covering registration, breach detection, audit trail
Adds typescript@^5.4.5 and @zeroquery/sdk@workspace:* for the new @zeroquery/intent-registry package. Resolves ERR_PNPM_OUTDATED_LOCKFILE CI failure on frozen-lockfile install.
- Add @types/node to devDependencies (fixes TS2307: Cannot find node:crypto) - Add lib/types to tsconfig.json for node builtin declarations - Fix type cast (TS2352): use double-assertion pattern for xrplAnchor mutation - Fix test import: use dist/index.js (post-build) matching relay test pattern - Update pnpm-lock.yaml for @types/node addition
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ScriptMaster Labs Institutional Audit — ZeroQuery Agent Discovery
Changes
llms.txtAGENTS.mdllms.txt
Describes the ZeroQuery Proof-of-Intent protocol for AI agents that encounter this service:
https://zeroquery.network/mcpwith 3 tools (resolve_did,broadcast_intent,open_escrow)AGENTS.md
Dev brief for AI agents contributing to this codebase:
Generated by Claude Code