Reference runner

A wallet agent should prove policy before it asks for a signature.

This reference flow is the practical bridge between the Sage widget, local wallet policy, exact transaction simulation, and durable receipts. It is testnet-first and deliberately non-custodial.

Reference JSON Policy-check API Try playground

Current status

testnet reference flow

A reference flow for host-owned local wallet agents on Ergo testnet. It is not wallet software, not a remote signer, and not mainnet readiness evidence.

Custody

host-owned

Network

testnet

Signer

local wallet

Mainnet

closed

Flow

The reference runner is a narrow corridor.

Every stage has one actor, one output, and one reason to exist. That makes the flow easier to inspect, test, and reject before signing.

Load policy

host app

Read a local policy profile that matches the wallet-agent policy schema.

WalletAgentPolicyProfile

Receive intent

sage widget or host app

Accept a portable payment intent with amount, receiver, reserve, task hash, and receipt expectations.

SagePaymentIntent

Normalize action

local agent

Map the payment intent into one proposed action before asking for a policy verdict.

WalletAgentProposedAction

Check policy

local agent or host app

Call the policy-check API and persist allow/deny reasons.

WalletAgentPolicyVerdict

Simulate transaction

wallet layer

Build and inspect one exact testnet transaction before the user is asked to sign.

Unsigned exact transaction summary

Ask wallet to sign

host owned wallet

Request a signature only for the simulated transaction. Never expose secrets to the page, widget, or API.

Signed transaction bytes or transaction id

Broadcast

host app or wallet

Broadcast only the transaction that matched the policy verdict and simulation summary.

Transaction id or Note box id

Verify

sage or verifier

Verify the Note box id against quote, task hash, receiver, reserve, amount, and expiry.

Verification Receipt JSON

Retain receipt

host app and public receipt api

Store or link Agreement JSON, Verification Receipt JSON, Settlement Receipt JSON, and public receipt URL.

Full receipt bundle or explicit chain_proof_only status

Runner skeleton

The wallet layer owns the dangerous part.

The page, widget, and API can help produce intent and verdicts. They do not receive seed phrases, broad signing rights, or custody authority.

The site does not custody funds.

The reference flow does not grant autonomous mainnet signing authority.

The policy-check API does not sign, broadcast, store private keys, or replace wallet confirmation.

Remote prompt text cannot override caps, allowlists, expiry limits, or receipt retention rules.

Reference skeleton

const profile = await loadLocalPolicyProfile()
const intent = await getSagePaymentIntent(question)
const proposedAction = normalizeIntentForPolicyCheck(profile, intent)

const verdict = await fetch(
  "https://www.ergoblockchain.org/api/agent-economy/wallet-agent/policy-check",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ profile, proposed_action: proposedAction }),
  },
).then((res) => res.json())

if (!verdict.allowed) {
  throw new Error(verdict.reasons.join(", "))
}

const unsignedTx = await wallet.simulateExactNoteTransaction(intent)
const signedTx = await wallet.signExactTransaction(unsignedTx)
const noteBoxId = await wallet.broadcast(signedTx)
const receipt = await verifySagePaymentAndFetchReceipt(intent, noteBoxId)
await retainReceipt(receipt)

Intent to policy action

{
  "network": "testnet",
  "action": "sign_specific_transaction",
  "amount": intent.amountErg,
  "recipient": intent.receiverAddress,
  "reserve": intent.reserveBoxId,
  "expiry_height_delta": intent.expiryHeightDelta,
  "task_hash": intent.taskHash,
  "receipt_expected": true
}

Reference checks

Policy profile is loaded before any quote or signing request.

The proposed action uses the same network, receiver, reserve, amount, fee, expiry, and task hash as the payment intent.

A denied policy verdict stops the flow before wallet UI.

Human confirmation is required when the policy threshold is exceeded.

The wallet signs one exact simulated transaction, not broad agent authority.

Receipt URL and receipt completeness are retained after verification.

Mainnet stays disabled until external review and audit-bound script identity exist.

Entrypoints

Human docs and machine contracts point to the same flow.

The runner is intentionally redundant with the API contracts. A developer can read the page, while an agent or test harness can inspect the JSON.

human page

https://www.ergoblockchain.org/build/agent-payments/wallet-agent-runner

machine api

https://www.ergoblockchain.org/api/agent-economy/wallet-agent/reference-flow

public manifest

https://www.ergoblockchain.org/agent-economy/wallet-agent-reference-flow.v0.json

policy playground

https://www.ergoblockchain.org/build/agent-payments/policy-playground

policy schema

https://www.ergoblockchain.org/agent-economy/wallet-agent-policy.schema.v0.json

policy check schema

https://www.ergoblockchain.org/agent-economy/wallet-agent-policy-check.schema.v0.json

policy template

https://www.ergoblockchain.org/agent-economy/wallet-agent-policy.profile.template.json

policy check api

https://www.ergoblockchain.org/api/agent-economy/wallet-agent/policy-check

sage widget

https://www.ergoblockchain.org/agent-economy/sage-widget

quickstart

https://www.ergoblockchain.org/build/agent-payments/quickstart

receipt api template

https://www.ergoblockchain.org/api/sage/receipt/{receiptId}