Teach your coding agent to build on Ritual

What it teaches

The 10 behavioral rules that govern how the agent operates on Ritual Chain. Loaded automatically by every entry point.

The 10 Rules

• 1. Track Cost: turn budget governs all thresholds
• 2. Distrust Priors: Ritual violates Ethereum training data
• 3. Lazy Elicitation: 0-5 JIT questions, never a static form
• 4. Interleave Build+Debug: verify after every irreversible action
• 5. Circuit Breaker: detect trajectory divergence, stop before wasting budget
• 6. Search Before Asking: exhaust 5-step resolution hierarchy first
• 7. Ask at Forks: only for expensive preference-based forks
• 8. Anti-Slop: dimensional decomposition for UI artifacts
• 9. Verify Non-Interactively: per-skill checks + 12-step E2E journey
• 10. Scope to Project Directory: all writes within project root, no cross-pollution

What it teaches

The complete non-interactive verification system.

Three layers

• Per-skill checks (T1-T4 tiers): static analysis, simulation, deployed verification, runtime
• Cross-skill integration: 8 interface checks (ABI field counts match, addresses match, event names match, etc.)
• Unified 12-step E2E journey: chain reachable → wallet funded → executor available → contract deployed → wallet funded & balance escrowed → precompile simulates → TX mines → result delivered → result decodable → state updated → frontend renders → backend indexed

What it teaches

How the agent generates contextual questions instead of using a static form.

How it works

• Parses user's first message for signals (precompile type, statefulness, frontend needs, etc.)
• Identifies top-K unresolved dimensions from a 12-dimension architectural universe
• Generates 0-5 questions with 4 contextualized options each
• >200 words from user = infer everything, confirm only
• Almost nothing from user = route to front door

What it teaches

Self-awareness for the agent: knowing when the current approach isn't converging.

How it works

• Weighted progress markers: chain connection (1), deploy (3), settle (5), E2E (8)
• Stall thresholds by phase: scaffolding (3 turns), contracts (5), frontend (4), integration (6)
• Immediate break on: error oscillation, scope creep into verified files, user frustration signals
• Proposes: simplify scope / pivot architecture / pause and hand back

What it teaches

Before the builder agent starts writing code, this skill takes the user's raw idea and maps every capability to the optimal Ritual precompile or system contract. The builder receives a structured spec instead of a vague prompt.

How it works

• Reads the overview and precompiles skills to load the full capability surface
• Decomposes the idea into capabilities (data ingestion, AI inference, scheduling, privacy, etc.)
• Maps each capability to a specific precompile address using a comprehensive mapping table
• Detects the 1-phase async constraint (only one short-running async call per TX) and resolves via Scheduler chaining
• Detects additional constraints: sender lock, block time, encrypted input + auto-selection conflicts
• Checks reference contracts in examples/registry.json for reusable patterns
• Surfaces implicit requirements (RitualWallet deposit, callback handlers, storage config)
• Outputs a structured spec with mapped capabilities, constraints, required skills, and off-chain components

What it teaches

When the user doesn't know what to build, this skill searches the web for what's trending in blockchain and AI right now, filters for ideas that require Ritual-specific precompiles, and presents 3-5 concrete buildable app ideas.

How it works

• Three parallel web searches for current trends (varies by date)
• Hard filter: each idea must map to a specific precompile address (0x08XX)
• Deduplication against static examples already shown elsewhere
• Each idea includes: one-line pitch, why now (from search), why Ritual (which precompile), complexity rating
• Fallback to static examples if search fails

Constraints

• 3-5 ideas, never more
• At least one simple (1 precompile) and one ambitious (3+)
• Every idea must be buildable in one session
• No generic blockchain apps that work on any EVM chain

What it teaches

The complete Ritual Chain mental model. Three execution models (synchronous, short-running async, long-running async), the 9-state async transaction lifecycle, TEE trust model, executor selection, and all system contracts.

Prior Correction

8 Ethereum assumptions that are wrong on Ritual:

• writeContractAsync breaks on async precompiles. Use useSendTransaction
• msg.sender in callbacks = AsyncDelivery proxy, not the user
• Only one short-running async call per transaction
• Fees are RitualWallet deposits, not gas
• Block time is ~350ms, not 12s
• Receipts have spcCalls field with precompile results
• Sender lock: one async job per EOA at a time
• No Chainlink/ERC-4337/Gelato. Ritual has native equivalents

What it teaches

Input/output ABI for every precompile, with field counts, Solidity encoding, and viem TypeScript patterns.

Precompile Categories

What it teaches

Chain ID 784, RITUAL currency, EIP-1559 only. Complete Foundry and Hardhat configuration templates. System contract addresses. Deployment scripts with explorer verification. RPC endpoints for HTTP and WebSocket.

What it teaches

The Ritual visual language: dark-mode-first terminal aesthetic. Fonts: Izoard (display), Barlow (body), JetBrains Mono (code). Color semantics: green = trust/success, pink = AI/compute, lime = data, gold = value. 9-state lifecycle UI components. WCAG 2.1 AA accessibility with focus-visible rings.

What it teaches

The HTTP Call precompile. Short-running async model: result arrives in the same transaction via spcCalls.

Key patterns

• SECRET string replacement for API keys
• piiEnabled flag for secret string replacement and PII redaction
• JQ post-processing via the JQ precompile (0x0803)
• Method codes: GET=1, POST=2, PUT=3, DELETE=4, PATCH=5
• One short-running async call per TX. Cannot chain with LLM in same TX

What it teaches

The LLM precompile. 30-field ABI input. OpenAI-compatible chat completions with tool/function calling and structured output (JSON mode).

Key patterns

• SSE streaming via EIP-712 signed events
• Temperature and topP scaled ×1000 (0.7 = 700)
• Private LLM via ECIES encryption to executor
• Model selection via TEEServiceRegistry capability query

What it teaches

Two agent precompiles: Persistent Agent (0x0820) for stateful with memory, Sovereign Agent (0x080C) for autonomous execution.

Key patterns

• 2-phase submit → callback with tools (web_search, code_execution)
• Storage references for persistent state across sessions
• Delivery config: target address + selector + gas limit

What it teaches

The Long HTTP precompile for operations that take minutes to hours.

Key patterns

• Submit → poll → deliver with JQ extraction
• pollIntervalBlocks + maxPollBlock configuration
• taskIdMarker for result identification
• Scheduler integration for recurring long jobs

What it teaches

Image (0x0818), Audio (0x0819), and Video (0x081A) precompiles.

Key patterns

• Encrypted storage credentials for S3/IPFS/Arweave
• Output: URI + content hash
• Executor Capability IDs: 7 (image), 8 (audio), 9 (video)

What it teaches

How to use the Scheduler contract (0x4E0abeE2233D73E66382b45244F7459B34E1490E) to schedule delayed and recurring precompile calls on Ritual Chain. Execution is block-based, not time-based.

Key patterns

• setTimeout / setInterval for Solidity: delayed and recurring on-chain calls
• FSM: SCHEDULED → EXECUTING → COMPLETED/FAILED
• Uses TxScheduled (type 0x10) system tx from sender 0x0000...00fa7e
• Predicates for conditional execution (only run when a condition is true)
• RitualWallet must be funded before each execution (just-in-time deposits supported)

What it teaches

Secret management for Ritual precompiles.

Key patterns

• ECIES encryption to executor public key
• SECRET string replacement in precompile inputs
• Private outputs via userPublicKey field
• SecretsAccessControl for delegated access
• Contract-owned vs EOA-owned secrets with different msg.sender rules

What it teaches

X402 micropayment protocol for paid APIs via the HTTP and Long-Running HTTP precompiles.

Key patterns

• ECIES-encrypted payment credentials
• Budget management per API call
• Shared credential patterns
• Flows through HTTP (0x0801) and Long-Running HTTP (0x0805), not a separate precompile

What it teaches

Native passkey authentication on Ritual Chain using the TxPasskey transaction type (0x77). Users sign transactions with biometrics (Face ID, Touch ID, fingerprint sensors, or hardware security keys) instead of managing private keys.

Key patterns

• P-256 WebAuthn signature verification
• Wallet-less onboarding: users create accounts with a fingerprint or face scan
• Recovery patterns and dual-auth (passkey + traditional EOA)

What it teaches

How to write consumer contracts that correctly encode inputs, decode outputs, and handle results from every type of Ritual precompile.

Key patterns

• ABI encoding/decoding for precompile inputs and outputs
• Short-running result decoding from spcCalls in the transaction receipt
• Long-running callback handlers: implement onResult(bytes32 jobId, bytes result) for async delivery
• Scheduled execution: recurring and delayed contract calls via the Scheduler
• Fee deposits via RitualWallet.deposit(lockDuration) before submitting async calls
• Job lifecycle events: track async and scheduled job state (committed, settled, delivered, expired)

What it teaches

The RitualWallet fee management contract.

Key patterns

• deposit(lockDuration) → funds locked until block.number + lockDuration → withdraw(amount) after lock expires
• Lock duration is user-controlled (set at deposit time to cover your async TTL)
• Lock is monotonic: new deposits only extend, never shorten the lock
• depositFor(user, lockDuration) to fund another address
• Must fund and lock BEFORE submitting async calls. Lock duration must cover the precompile TTL