Payment Proofs -- Treeship

Creating verifiable payment receipts with Treeship artifacts and approval nonces.

Payment proofs in Treeship are standard artifacts that record payment events with signed, verifiable receipts. The key mechanism is the approval nonce -- a cryptographic binding that proves a human authorized the payment before it happened.

Recording a payment

Use action artifacts to record each payment step:

# Record payment initiation
treeship attest action \
  --actor agent://payment-processor \
  --action payment.initiate \
  --subject '{"amount": 5000, "currency": "USD", "recipient": "vendor_abc"}'

# Record payment confirmation, chained to initiation
treeship attest action \
  --actor agent://payment-processor \
  --action payment.confirm \
  --parent art_initiate123 \
  --subject '{"transaction_id": "tx_789", "status": "completed"}'

Verification

Anyone with the artifact can verify that:

The payment record was signed by the expected key
The content has not been modified since signing
The chain from initiation to confirmation is unbroken

treeship verify art_confirm456

Payments with approval

For payments that require human authorization:

# Finance director creates an approval.
# --expires takes an RFC 3339 timestamp, not a duration like "1h".
treeship attest approval \
  --approver human://alice \
  --allowed-action payment.execute \
  --allowed-actor agent://payment-processor \
  --expires 2026-08-19T12:00:00Z

# The approval prints the nonce the action must echo back:
#   → nonce: 90671ba228b375ca304c2233914f68e1

# Payment agent uses the approval nonce
treeship attest action \
  --actor agent://payment-processor \
  --action payment.execute \
  --approval-nonce 90671ba228b375ca304c2233914f68e1

The verifier confirms that the approval nonce matches a valid signed approval (binding) and -- if the approver set scope flags -- that the action's actor / action / subject fall inside the approval's allow-lists (scope). Replay is enforced at attest time by the local Approval Use Journal, which reserves a use before the action is signed, so a nonce cannot be spent twice on this device or workspace. Distributed replay across machines additionally needs a Hub-signed journal checkpoint; the verifier for that exists, the Hub-side signer does not yet.

Using treeship wrap

For payments executed as shell commands, treeship wrap captures the execution itself -- the exit code, timing, and command line -- in a signed artifact:

# Approve the payment
treeship attest approval \
  --approver human://alice \
  --allowed-action payment.execute \
  --allowed-actor agent://payment-processor \
  --expires 2026-08-19T12:00:00Z
#   → nonce: 90671ba228b375ca304c2233914f68e1

# Run the payment; wrap signs what actually executed
treeship wrap \
  --actor agent://payment-processor \
  --action payment.execute \
  -- python execute_payment.py --order ord_123
#   → art_7c1d... (the execution artifact)

# Bind that execution to the approval that authorized it
treeship attest action \
  --actor agent://payment-processor \
  --action payment.execute \
  --approval-nonce 90671ba228b375ca304c2233914f68e1 \
  --parent art_7c1d...

treeship wrap has no --approval-nonce flag. Approval binding lives on treeship attest action, which is why this is two commands: wrap proves what ran, attest action proves what authorized it, and --parent chains them.

Push to Hub for a shareable verification URL:

treeship hub push art_confirm456
# hub_url: https://treeship.dev/verify/art_confirm456

Share the URL with counterparties, auditors, or compliance teams. They can verify the receipt in their browser without installing Treeship.

Treeship v2 will add ZK proofs for payment verification, allowing you to prove properties like "payment was under $10,000" or "recipient is on the approved vendor list" without revealing the actual values.

Payment Proofs

Recording a payment

Verification

Payments with approval

Using treeship wrap

Sharing payment proof

On this page