From c1e13bf2547349c6beee85d37c4092d5ee4837a8 Mon Sep 17 00:00:00 2001 From: Layer Tau <282960173+layertau@users.noreply.github.com> Date: Wed, 20 May 2026 01:14:46 +0000 Subject: [PATCH] docs: document block-pinned component reads --- .claude/skills/wavs/SKILL.md | 8 ++++++++ .claude/skills/wavs/flows/component-dev.md | 2 ++ 2 files changed, 10 insertions(+) diff --git a/.claude/skills/wavs/SKILL.md b/.claude/skills/wavs/SKILL.md index da41ea1f6..b90ce5f47 100644 --- a/.claude/skills/wavs/SKILL.md +++ b/.claude/skills/wavs/SKILL.md @@ -14,6 +14,14 @@ WAVS runs off-chain computation as sandboxed WebAssembly (WASI) components trigg --- +## Deterministic On-Chain Reads + +Treat the trigger/event block height as the canonical snapshot for on-chain data that relates to that trigger. When a component performs EVM, Cosmos, or other RPC reads and the client/API supports it, pass the trigger block number or block height explicitly instead of reading `latest` state. + +Avoid mixing historical trigger data with unpinned latest-state reads. Pinning reads to the trigger block improves replayability and prevents nondeterministic state/timestamp mismatches, such as an oracle response whose `updatedAt` appears newer than the block timestamp because an RPC backend served cached state from a different snapshot. + +--- + ## MCP Setup The `wavs:` MCP tools below require `wavs-mcp` to be running and registered with Claude Code. diff --git a/.claude/skills/wavs/flows/component-dev.md b/.claude/skills/wavs/flows/component-dev.md index 0a6225f26..5b2bf19f0 100644 --- a/.claude/skills/wavs/flows/component-dev.md +++ b/.claude/skills/wavs/flows/component-dev.md @@ -77,6 +77,8 @@ use example_helpers::trigger::{decode_trigger_event, encode_trigger_output}; ## Host APIs +For on-chain reads related to a trigger, use the trigger's block height as the canonical snapshot. Pass that block number/height to EVM, Cosmos, or RPC calls when supported, and avoid mixing historical trigger data with unpinned `latest` reads. + ```rust host::config_var("my-key") // → Option; reads service config host::log(host::LogLevel::Info, "msg"); // levels: Debug, Info, Warn, Error