Blockchain, Wallets, and Agent Payments
Agents increasingly have access to wallets and use blockchain for payments, attestation,
and on-chain activity. This document defines the optional frontmatter extensions for Phase 12,
now active on feature/phase12-blockchain-frontmatter. Core (Phases 1–10) and Hub (Phase 11)
are unchanged. See SPEC.md frontmatter and Hub list/MCP filters for these fields (network, wallet_address, tx_hash, …).
Naming note: The existing --chain flag and frontmatter causal_chain_id refer to causal
chains of notes (see INTENTION-AND-TEMPORAL). For blockchain we use network (not chain) to
avoid collision.
1. Optional frontmatter fields
All fields are optional. Notes without them are fully valid. No Motoko schema change is required — frontmatter is stored as opaque JSON in the canister.
| Field | Type | Example | Description |
|---|---|---|---|
network |
string | icp, ethereum, sepolia |
Blockchain network identifier. Enables filter by network. |
wallet_address |
string | rrkah-fqaaa-aaaaa-aaaaq-cai |
Wallet principal, address, or account ID. Enables filter by wallet. |
tx_hash |
string | 0xabc123… |
On-chain transaction hash or ICP transaction ID. |
payment_status |
string | pending, settled, failed |
Status for payment-tracking notes. |
amount |
number or string | 1.5, "100 ICP" |
Transfer amount. String allows currency suffix. |
currency |
string | ICP, ETH, USDC |
Token or currency symbol. |
direction |
string | sent, received |
Transfer direction from the wallet's perspective. |
confirmed_at |
ISO timestamp | 2026-04-02T18:00:00Z |
On-chain confirmation time (may differ from note date). |
block_height |
integer | 12345678 |
Block number when tx was included. |
air_id |
string | air-abc123 |
AIR attestation ID when this note has an on-chain attestation. |
Recommended payment_status conventions
| Value | Meaning |
|---|---|
pending |
Submitted but not yet confirmed |
settled |
Confirmed on-chain |
failed |
Reverted, rejected, or timed out |
cancelled |
Intentionally cancelled before submission |
Recommended tag conventions
payment— any note about a financial transferon-chain— any note referencing on-chain activityattestation— notes linked to an AIR attestationicp-tx— ICP-specific transaction notesagent-activity— notes written by an automated agent
2. CLI / API filters (implemented in Phase 12)
--network <id>— filterlist-notesresults to a specific blockchain network.--wallet <address>— filter by wallet address (exact match after normalization).--payment-status <status>— filter by payment status enum.- Hub UI: Network and Wallet dropdowns populated from vault facets. Payment status
Quick chips for
pending,settled,failed.
3. Capture and import
- On-chain events → vault: Capture plugins (Phase 5 contract) write notes to the inbox when
on-chain events occur. Same contract:
path,frontmatter(source,date,source_id), plus the new optional fields above. No new core phase required. - Import (future): Optional import source type for "wallet export" or "transaction history" that produces vault notes with the reserved frontmatter. Format TBD.
4. AIR and attestation
AIR (Phases 4, 8) already provides an attestation hook before write/export. Phase 12+ can add an
optional backend where the attestation is recorded on-chain (e.g. signing canister, ICP).
air_id in frontmatter is the link back. No change to AIR's interface.
5. Summary
| Area | Status |
|---|---|
Frontmatter fields (network, wallet_address, tx_hash, payment_status, amount, currency, direction, confirmed_at, block_height, air_id) |
Implemented — Phase 12 |
List-notes filters (--network, --wallet, --payment-status) |
Implemented — Phase 12 |
| Hub UI filter dropdowns (Network, Wallet) + Quick chips (payment status) | Implemented — Phase 12 |
Hosted facets (networks, wallets in /api/v1/notes/facets) |
Implemented — Phase 12 |
| Keyword search scope (network, wallet_address, tx_hash in match fields) | Implemented — Phase 12 |
| Capture plugins (on-chain events → inbox) | Phase 5 contract (no code change) |
| Import source (wallet/tx history CSV) | Future |
| AIR on-chain backend | Future |
MCP tool filter params (network, wallet) |
Follow-on |