AgentKeys AuditEnvelope v1 decoder

[crossagent-production-app]

Summary

Refs #12.

Adds AgentKeys AuditEnvelope v1 decoding support, canonical CBOR handling, op_kind typed renderers with Unknown(byte) fallback, envelope hash verification, immutable-by-hash worker fetch/cache, and AgentKeys REST audit endpoints.

Latest update also wires the actual Heima CredentialAudit address supplied in issue #12 comments (0x63c4545ac01c77cc74044f25b8edea3880224577) and supports the live current Heima event ABI:

• AuditAppendedV2(bytes32,bytes32,uint8,bytes32) strict worker-backed path remains supported.
• AuditAppended(bytes32,bytes32,bytes32,uint8,uint256,bytes32) live ABI is decoded for existing mainnet logs.
• /agentkeys/audit/<operator_omni> queries both V2 and current event topics, preserves pagination/filtering, and returns current-event rows even when the worker has no envelope body yet (envelope_available=false).
• Added a real Heima Mainnet capture fixture from the live CredentialAudit contract: tests/fixtures/agentkeys/heima-mainnet-current-auditappended.jsonl.

Verification

• go test ./internal/agentkeys -count=1 passes, 16 tests.
• go test -c -o /tmp/subscan-http.test ./internal/server/http compiles.
• go test -c -o /tmp/subscan-dao.test ./plugins/evm/dao compiles.
• jq -c . tests/fixtures/agentkeys/heima-mainnet-current-auditappended.jsonl validates 13 live-capture JSONL rows.

Delivery Evidence Summary

Change:

• Added AuditEnvelope v1 decoder and deterministic CBOR support.
• Added known op_kind typed body rendering with Unknown(byte) fallback.
• Added worker envelope fetch/hash verification/cache and REST envelope proxy route.
• Added live Heima current-event decode/query compatibility and real chain capture fixture.

Objective Evidence:

• AgentKeys decoder, CBOR, V2 event, current live event, unknown fallback, best-effort worker-missing, and live fixture tests pass.
• HTTP and DAO packages compile with the updated AgentKeys row plumbing.
• Real Heima current-event hashes in the capture returned worker 404 at capture time, so current-event rows are preserved with envelope_available=false instead of failing the whole page.

Risks / Not Covered:

• This PR is not a full issue AgentKeys: decoder + per-op_kind renderer for AuditEnvelope v1 (Phases D + E) #12 closure until worker-backed V2 AuditAppendedV2 / AuditRootAppendedV2 canonical demo capture and Rust cross-language vectors exist.
• Full repo go test ./... is still not the focused verification path here because unrelated packages require repo runtime config or currently fail outside AgentKeys.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
subscan-essentials	Ready	Preview, Comment	May 21, 2026 5:14pm

[crossagent-production-app]

Delivery Evidence Summary

Change:

• Confirmed Heima CredentialAudit is no longer treated as an address dependency: chain_id=212013 and contract=0x1801ded1a4FBD8c9224Ab18B9EcbB293B8674c06 are now AgentKeys constants.
• Scoped GET /agentkeys/audit/<operator_omni> and GET /agentkeys/audit/root/<merkle_root> EVM log queries to the confirmed CredentialAudit contract address, with AGENTKEYS_CREDENTIAL_AUDIT_CONTRACT override for non-main deployments.
• Added chain_id and contract_address metadata to typed row pages, individual typed rows, and root responses so downstream evidence can confirm the Heima source contract.
• Updated tests/fixtures/agentkeys/OPERATOR_INPUT_BLOCKERS.md to remove the contract address from remaining dependencies and keep only V2 deploy block/lower bound, real V2 log capture, Rust vectors, and bulk replay artifacts.

Objective Evidence:

• go test ./internal/agentkeys -count=1 exit code 0, passed: AgentKeys decoder and typed row/root tests pass with Heima chain and CredentialAudit response metadata.
• go test ./internal/agentkeys -run 'TestDecodeTypedAuditRowsAndRootLeaves|TestUnknownOpKindOpaqueArrayBodyDoesNotBreak|TestEnvelopeCacheOnlyStoresVerifiedBodies' -count=1 -v exit code 0, passed: Focused coverage confirms root/row decoding, future unknown CBOR fallback, and worker fetch plus keccak256 verification cache behavior.
• go test $(find internal/server/http -maxdepth 1 -name '*.go' ! -name '*_test.go') exit code 0, passed: Changed HTTP route code compiles without package test init.
• go test $(find plugins/evm/dao -maxdepth 1 -name '*.go' ! -name '*_test.go') exit code 0, passed: EVM DAO helper code compiles.
• npx --yes playwright screenshot --browser=chromium --viewport-size=1280,720 <AgentKeys CredentialAudit scope data URL> <worktree>/.crossagent/agentkeys-credentialaudit-scope.png exit code 0, passed: Browser validation command rendered the CredentialAudit scope evidence page. Screenshot was kept out of git.

Visual Evidence:

• 

Reviewer:

• CrossAgent developer self-verification on commit 716754a; PR AgentKeys AuditEnvelope v1 decoder #13 remains Refs AgentKeys: decoder + per-op_kind renderer for AuditEnvelope v1 (Phases D + E) #12 and is ready for reviewer follow-up on the CredentialAudit-scoped audit query change.

Risks / Not Covered:

• Remaining operator input: V2 deploy block or eth_getLogs lower bound for the confirmed CredentialAudit events.
• Remaining operator input: real AuditAppendedV2 and AuditRootAppendedV2 transaction/log captures plus worker CBOR responses from Heima Mainnet.
• Remaining operator input: Rust canonical CBOR vector artifacts for cross-language determinism checks.
• Remaining operator input: mainnet bulk replay artifacts over the confirmed contract range.
• Full go test ./... still stops on pre-existing config/DB/vet/mock setup issues outside this AgentKeys slice.

Generated at: 2026-05-21T14:28:47.525Z

[crossagent-production-app]

CrossAgent follow-up review note:

The current delivery gate passes, but the Visual Evidence is too weak for a high-quality human review: it is a static validation screenshot, not evidence from the actual decoder/API output. I am reopening the implementation loop on this PR to add stronger objective evidence and replace/supplement the visual proof with a fixture-backed API/decoder validation view.

Target for the follow-up pass:

• Use real decoded fixture/API output in the visual evidence, not a hand-written status card.
• Show known renderers plus Unknown(byte) fallback and hash verification state.
• Re-run focused Go tests and publish a refreshed App-auth evidence comment once complete.

[crossagent-production-app]

CrossAgent 继续工作请求：这个 PR 目前不要作为 #12 的完整闭环合并。

当前实现只覆盖了 AgentKeys AuditEnvelope v1 的解码/渲染夹具验证，以及 raw envelope proxy。Issue #12 仍然缺少这些交付项：

1. 实现 GET /agentkeys/audit/<operator_omni>，返回 paged typed TypedAuditRow，并支持 issue 中要求的过滤/排序语义。
2. 实现 GET /agentkeys/audit/root/<merkle_root>，返回 root metadata / leaves / proof-oriented typed rows。
3. 补充真实 Heima V2 tx capture 或 bulk replay artifact；如果缺少链上输入，必须明确发布 operator blocker，而不是把 fixture 当作完整交付。
4. 补充 cross-language Rust canonical vector artifacts，证明 Go decoder 与 Rust reference vectors 一致；如果 reference 不可用，同样要发布 blocker。
5. 强化 Unknown(byte) 兼容路径：合法 future/reserved op_kind 的 op_body 不应因为当前 CBOR parser 不认识数组/未来 shape 而直接 crash，应能以 opaque/unknown typed row 暴露。
6. PR body 当前 Fixes #12 太激进；只有上述 checklist 真正完成并重新发布 evidence 后，才适合用完整关闭语义。

请继续在当前 PR/branch 上完成下一轮实现，并在完成后重新发布测试与 evidence。

[crossagent-production-app]

CrossAgent follow-up request:

请继续做一轮，不要把 mock / hand-crafted-only fixture 当作 #12 的完成证据。Hanwen 已确认 CredentialAuditV2 链上有真实数据，所以这一轮请按真实数据链路闭环：

1. 从 issue AgentKeys: decoder + per-op_kind renderer for AuditEnvelope v1 (Phases D + E) #12 中扫描并确认 CredentialAudit V2 合约信息；如果正文仍未提供 exact address / deploy block，请在 PR 中明确向 operator 请求 blockheight、合约地址和可复现 tx capture，不要自行用 mock 替代。
2. 用 Heima Mainnet chain ID 212013 的真实 AuditAppendedV2 / AuditRootAppendedV2 日志生成 capture manifest，至少包含 txhash、block_number、log_index、topics、op_kind、envelope_hash。
3. 对每个真实 envelope_hash 调 worker GET /v1/audit/envelope/<hash>，校验 keccak256(canonical_cbor_bytes) == envelope_hash，并把 decoded typed rows 写入 tests/fixtures/heima-mainnet-canonical-demos.jsonl。
4. 补齐 issue 要求的 cross-language Rust vectors、unknown op_kind 250/255 negative-path、mainnet bulk replay artifact；如果 operator 资料缺失，产出 blocker，而不是声明完成。
5. PR 语义保持 Refs #12，只有五类 artifact 和 live endpoint 验证都齐了，才可以改成 closing wording。

验收重点：真实链上 event -> worker CBOR -> hash 校验 -> typed decode -> /agentkeys/audit/... REST 返回。请在 PR 证据里区分“已经完成的代码能力”和“仍依赖 operator 真实数据的阻塞项”。

[crossagent-production-app]

CrossAgent consolidation directive:

Please continue all remaining backend work in this PR (#13) only. Do not open another backend PR for this issue. PR #15 and issue #14 are being closed as an accidental split.

Carry forward the useful conclusion from the extra run, but apply it here: #12 still requires the real Heima Mainnet CredentialAuditV2 data loop. If exact contract address / deploy block / tx capture are missing, document that blocker inside this PR's evidence or files, and ask operator for the exact inputs. Do not use mock-only data as completion evidence.

Target branch remains cross-agent. Keep PR wording as Refs #12 until the five artifact classes and live endpoint validation are actually present. The final backend delivery should be one PR: this PR #13.

[crossagent-production-app]

Correction on the real-data blocker: the main audit contract address is already available from issues #3/#4. Use this as the current Heima Mainnet CredentialAudit address for #12 work:

• CredentialAudit: 0x1801ded1a4FBD8c9224Ab18B9EcbB293B8674c06
• Chain ID: 212013
• RPC: https://rpc.heima-parachain.heima.network

I also verified this address has non-empty bytecode via eth_getCode(..., latest). PR #13 has been updated to remove "contract address missing" from the blocker file.

Remaining blockers are now narrower: the V2 deploy block or safe eth_getLogs lower bound, real AuditAppendedV2 / AuditRootAppendedV2 tx/log capture, worker CBOR fetch/hash verification, Rust vectors, and bulk replay artifacts. Continue all backend work in this PR only.

[crossagent-production-app]

Operator chain facts for Issue #12 follow-up

I checked the live Heima CredentialAudit contract so PR #13 can stay on concrete data instead of treating the address as unknown.

• Chain: Heima mainnet 212013
• CredentialAudit: 0x1801ded1a4FBD8c9224Ab18B9EcbB293B8674c06
• First block with code: 9620427; current checked head: 9634227
• Live source shape in litentry/agentKeys/crates/agentkeys-chain/src/CredentialAudit.sol currently emits AuditAppended(bytes32,bytes32,bytes32,uint8,uint256,bytes32) with topic0 0x4e21321d01571fa35038552651b1fd51fdb2935e1c8566378607aecf7fa70919.
• eth_getLogs from 9620427..9634227 found 10 current-ABI AuditAppended logs. First observed sample: block 9621859, tx 0x8f6fb6b81cc4c82ecef1494e606445b5957c29c1eeca1d511f17ea5b4c1fe086.
• The Issue AgentKeys: decoder + per-op_kind renderer for AuditEnvelope v1 (Phases D + E) #12 V2 topics currently return 0 logs over the same range: AuditAppendedV2(bytes32,bytes32,uint8,bytes32) topic0 0x002ba1620cfafc48b84755f390622f21871ce52ec8ac0f07cbf59c16cf72880e; AuditRootAppendedV2(bytes32,bytes32,bytes32,uint64) topic0 0xd342148eba933b2fcc9cb3b168066b62245a76f11d98919d76eb69cfb66e48eb.

Actionable interpretation: do not keep “main audit contract address / deploy block” as a blocker. The remaining decision is narrower: either PR #13 supports the current live ABI as the real-data capture path, or the Issue #12 V2 deliverable still needs an operator-supplied V2 redeploy/tx capture and worker envelope artifact before this can honestly close. Please keep all backend work in PR #13 and do not open a new issue or PR.

[crossagent-production-app]

状态澄清：当前 Issue #12 的 CrossAgent status comment 显示 PR created，这只表示 PR #13 和 evidence gate 被识别到，不表示 #12 已完成，也不表示可以 merge。

PR #13 仍需要补齐真实 Heima CredentialAuditV2 闭环，至少包括：

• 真实 V2 tx/log capture 或明确支持当前 live ABI 的可复现 capture path；
• worker CBOR fetch + keccak256(canonical_cbor_bytes) == envelope_hash 校验；
• Rust cross-language canonical CBOR/hash vectors；
• mainnet bulk replay artifact；
• 用真实 rows 验证 GET /agentkeys/audit/<operator_omni> 和 GET /agentkeys/audit/root/<merkle_root>。

请继续把所有后端剩余工作收敛在这个 PR #13 内，不要新开后端 PR；在这些 artifact 与 live endpoint 验证齐全前，保持 Refs #12 语义，不要改为 closing wording。

[crossagent-production-app]

本轮已继续在现有 PR #13 原分支推进，未新开 PR：

• 使用 issue AgentKeys: decoder + per-op_kind renderer for AuditEnvelope v1 (Phases D + E) #12 comment 中确认的 Heima CredentialAudit 地址 0x63c4545ac01c77cc74044f25b8edea3880224577。
• 保留 AuditAppendedV2 严格 worker-backed 解码路径，同时新增 Heima live AuditAppended(bytes32,bytes32,bytes32,uint8,uint256,bytes32) 解码。
• /agentkeys/audit/<operator_omni> 现在同时查询 V2 topic 和当前 live topic，并对 current ABI 的 op_kind 做 data-word 过滤。
• 加入真实 Heima mainnet capture：tests/fixtures/agentkeys/heima-mainnet-current-auditappended.jsonl，13 条 current-event 日志。
• 当前 capture 中 worker envelope GET 返回 404，因此 HTTP row 会保留链上事实并标记 envelope_available=false，不会让整页 502。

验证：

• go test ./internal/agentkeys -count=1 通过，16 tests。
• go test -c -o /tmp/subscan-http.test ./internal/server/http 编译通过。
• go test -c -o /tmp/subscan-dao.test ./plugins/evm/dao 编译通过。
• jq -c . tests/fixtures/agentkeys/heima-mainnet-current-auditappended.jsonl 验证 13 行 JSONL fixture。

[YoshiyukiSakura]

Local real-DB integration evidence (2026-05-22 CST)

Verified this PR against the scanned Heima DB through a local SSH tunnel, without deploying over the test environment.

• Local backend: http://127.0.0.1:4399, connected to the remote scanned MySQL/Redis via SSH tunnel.
• CredentialAudit: 0x63c4545ac01c77cc74044f25b8edea3880224577.
• Operator sample: 0x941cb1c3260518bbf40eac7d02663517fc7cff304d9b03e80d2cc54126c6bef2.
• Root sample: 0x32301a0bd7c9c1d064f0d3891c78ad00a6d9fa758ebb14a1a0ff64eb4f4ca3aa.

Observed API results:

• GET /agentkeys/audit/<operator>?limit=50 returned 9 live AuditAppended rows, all CredStore, block range 9625257..9632387, envelope_available=false.
• GET /agentkeys/audit/root/<merkle_root> returned current live AuditRootAppended, current_sequence=28, entry_count=2, leaves=2, rows=2.
• Worker probe for emitted envelope hashes still returns HTTP 404, so worker-backed CBOR body/hash proof is still not closed.

Frontend alignment:

• The matching UI PR now renders these chain-only live rows from the local backend and no longer needs to wait for a deployed backend just to capture visual evidence.
• Local visual evidence artifacts exist in the UI worktree under test-results/agentkeys-local-evidence/: live-operator-rows.png and live-root-rows.png.

Current conclusion: this removes the frontend/API-deployment waiting blocker, but #12 still should not be closed until the worker envelope 404 / protocol acceptance question is resolved.