ERGO
Local wallet-agent boundary

Wallet agents should sign less, know more, and keep policy local.

This spec defines the safety envelope for the next Ergo agent surface: local policy, explicit simulation, bounded signing, and receipt-first accountability. It is a testnet-first design contract, not custody software.

JSON specPolicy verdictWidget surface
Current posture
draft testnet safety spec

A safety specification for local wallet agents on Ergo. It is not wallet software, not custody infrastructure, and not mainnet readiness evidence.

Network
testnet_first
Signing
local only
Custody
non-custodial
Mainnet
closed

Allowed language

  • wallet-agent safety spec
  • local policy and simulation boundary
  • host-owned signing flow
  • testnet-first agent payment design

Forbidden language

  • autonomous mainnet trading bot is ready
  • the site can custody funds
  • wallet-agent policy is audited
  • users should grant unbounded signing authority

Never do

  • Never expose seed phrases, private keys, or wallet signing APIs to a remote page.
  • Never approve an unbounded spending permission for an LLM agent.
  • Never let prompt text override policy caps or recipient allowlists.
  • Never treat a remote quote as proof that a transaction is safe.
  • Never claim mainnet readiness before external review and audit-bound script identity exist.

Lifecycle

The only acceptable signing path.

Remote services may produce useful quotes, but they do not get signing authority. A local wallet-agent must move through policy, simulation, and exact transaction approval before any key is touched.

spec

Intent

Parse the user goal, budget, deadline, and allowed actions before requesting any quote.

required

Policy

Check every action against local caps, allowlists, time windows, and human-confirmation rules.

required

Quote

Treat remote quotes as untrusted input; bind receiver, amount, reserve, expiry, and task hash.

required

Simulate

Compute expected inputs, outputs, registers, fees, and receipt id before asking for a signature.

required

Approve

Show a human-readable transaction summary when policy requires confirmation.

required

Sign locally

Sign inside the user wallet or local agent process; never send private keys to the site or widget.

bounded

Broadcast

Broadcast only the transaction that matched simulation and policy checks.

required

Receipt

Store or link the receipt bundle so the user can prove what was authorized and settled.

Threat model

What the local agent must resist.

The main enemy is not only a bad transaction. It is any workflow that lets text, UI, or a remote quote bypass the user's local policy.

Prompt injection tries to convince the agent to ignore spending policy.

A malicious service returns a quote with a wrong recipient, value, reserve, or task hash.

A replayed or stale Note is presented as payment evidence for a new task.

A UI or host app asks for broad signing permission instead of a specific transaction.

An agent attempts market activity outside explicit user limits.

A signer or wallet extension leaks secrets into a web page or remote service.

Transaction checks

Every signature request must pass these checks.

This is the minimum transaction checklist for a wallet-agent before signing a Note payment, receipt flow, or future agent-to-agent action.

Check 1

Network matches the policy profile.

Check 2

Receiver address matches the quoted receiver and local allowlist.

Check 3

Reserve box id matches the quote and local allowlist.

Check 4

Amount, spent_today, and fee are strict decimal strings with no scientific notation.

Check 5

Amount is less than both per-action and daily spend caps, and spent_today is non-negative.

Check 6

Task hash is canonical hex and matches the canonical user intent and Agreement JSON.

Check 7

Expiry height is inside the policy window.

Check 8

Unknown policy or proposed-action fields fail closed.

Check 9

Receipt-retention mode is explicit and valid.

Check 10

Registers match the expected Note contract fields.

Check 11

No extra outputs, token movements, or data inputs are present without policy permission.

Check 12

Fee is inside the configured limit.

Check 13

Receipt URL and receipt id are recoverable after broadcast.

Policy profile

A wallet-agent starts with policy, not a prompt.

The policy profile is intentionally boring: caps, allowlists, expiry limits, confirmation thresholds, and receipt retention. That boring layer is what makes autonomous flows survivable.

Required fields

agent_id
network
daily_spend_cap
per_action_spend_cap
allowed_recipients
allowed_reserves
allowed_actions
requires_human_confirmation_above
expiry_height_limit
receipt_retention

Recommended defaults

network
testnet
daily spend cap
small explicit amount
per action spend cap
smaller than daily cap
allowed recipients
deny by default
allowed reserves
deny by default
allowed actions
quote, simulate, sign_specific_transaction, fetch_receipt
requires human confirmation above
any non-trivial amount
expiry height limit
short-lived
receipt retention
store receipt URL and hash locally

Machine contract

Policy verdict before wallet authority.

The policy-check API returns a deterministic allow/deny verdict before any host-owned wallet is asked to sign.

Policy schema

Canonical JSON shape for caps, allowlists, expiry windows, and receipt retention.

Profile template

A testnet-first profile starter with explicit recipients, reserves, spend caps, and allowed actions.

Policy-check API

Returns a machine-readable allow or deny verdict for a proposed local wallet action.

Boundary claims

  • policy-check signs transactions
  • policy-check proves a transaction is safe on mainnet
  • policy-check replaces wallet UI confirmation
POST /api/agent-economy/wallet-agent/policy-check
{
  "profile": "wallet-agent-policy.profile.v0",
  "proposed_action": {
    "network": "testnet",
    "action": "sign_specific_transaction",
    "amount": "0.005000000",
    "recipient": "allowlisted testnet recipient",
    "reserve": "allowlisted reserve",
    "task_hash": "canonical agreement hash",
    "receipt_expected": true
  }
}

Integration surfaces

Where this spec touches the live stack.

The wallet-agent layer is designed to sit beside Sage, MCP, receipts, and the review pack. It narrows signing authority instead of adding a new remote signer.

Policy playground

Lets developers mutate a proposed wallet action and inspect the live allow/deny verdict.

Reference runner

Shows the practical host-owned wallet-agent flow from policy profile to exact signing request and receipt retention.

Policy-check API

Returns a machine-readable allow/deny verdict for a local policy profile and a proposed testnet action.

Sage widget

Emits payment intent JSON and verifies a Note box id; it does not sign.

Receipt API

Returns the machine-readable source of truth for Agreement, Verification Receipt, Settlement Receipt, and chain proof.

MCP endpoint

Public machine-facing entry point for tool discovery and agent context.

Review pack

Defines what must be externally reviewed before stronger trust language.

Acceptance criteria

What a real implementation must prove.

This list turns the direction into a reviewable surface. A wallet-agent implementation should be judged by observable policy decisions, not by promises about autonomy.

A wallet-agent implementation can serialize its policy profile before any transaction request.

A wallet-agent implementation can call the policy-check API and persist a rejected verdict reason.

Every signing request references one exact simulated transaction.

A rejected policy check is recorded with a machine-readable reason.

A successful flow links to a full receipt bundle or clearly states chain_proof_only.

The implementation can run in testnet mode without mainnet claims.

Mainnet mode remains disabled until the external review and audit-bound mainnet identity gates are open.