PreparedEnvelope spec v0.1

Canonical spec: packages/tx-protocol/spec/v0.1/prepared-transaction.md.

TL;DR

PreparedEnvelope is a discriminated union on kind:

type PreparedEnvelope = EvmTxEnvelope | EvmBatchEnvelope | SignatureEnvelope
 
interface BaseEnvelope<K extends string, C> {
  $schema: string
  version: '0.1'
  kind: K
  id?: string                     // EIP-5792 idempotency
  issuedAt: string                // RFC3339
  expiresAt?: string
  nonce?: `0x${string}`
  producer?: Producer             // DID / CAIP-10 / ERC-8004 / URL, PQ-ready signing
  origin?: Origin                 // dApp URL + verify status
  content: C                      // kind-specific
  risk?: RiskAssessment           // unbound; wallet/scanner injects
  capabilities?: Capabilities     // EIP-5792 aligned open record
  meta?: Record<string, unknown>
}

Kinds

Implemented in v0.1

Reserved (declared, not validated today)

evm-userop (ERC-4337), evm-frame (EIP-8141), evm-7702 (set-code), mandate (AP2 / Visa TAP / Mastercard VI), intent (ERC-7683 / UniswapX / Anoma), psbt (Bitcoin), svm-tx (Solana), move-tx (Aptos/Sui), cosmos-tx (Cosmos SDK).

Security model

Off-chain fields (description, metadata, origin, risk, decoderRef, clearSigning, meta) are presentational and carry no cryptographic integrity on their own.

The authoritative representation of on-chain effect is {chain, calls[*].to, calls[*].data, calls[*].value} for EVM txs, or {scheme, domain, message} for signatures.

Policy engines, allowlists, and spend limits MUST validate on raw fields. Trusting description.short is a blind-signing pattern.

Two integrity layers:

1. Producer signature (producer.signature covers envelope bytes). Tampering in transit detected. Schemes: secp256k1, ed25519, p256 (implemented); ml-dsa-*, slh-dsa-* (reserved post-quantum NIST FIPS 204/205).
2. Wallet-side decoder re-verify. Consumer runs local decoder on calls[*].data, compares synthesized movements to producer's metadata.tokenMovements. Mismatch -> hard warning even with valid signature.

Attack-defense map

v0.1 closes gaps identified in 2024-2026 incident review:

Links

• Full spec v0.1 RFC
• @txkit/tx-protocol package README
• Examples
• OWS composition

Install

pnpm add @txkit/tx-protocol

Minimal usage

import { createEvmTx, validateEnvelope } from '@txkit/tx-protocol'
import type { EvmTxContent } from '@txkit/tx-protocol'
 
const content: EvmTxContent = {
  chain: 'eip155:1',
  calls: [ { to: '0x...', data: '0x...', value: '0x0' } ],
  validity: { notAfter: Math.floor(Date.now() / 1000) + 3600 },
  description: { short: 'Claim rewards', action: 'claim' },
  metadata: {
    protocol: 'my-protocol',
    tokenMovements: [],
    counterparties: [],
  },
}
 
const envelope = createEvmTx(content, {
  origin: { url: 'https://app.example.io', verifyStatus: 'VERIFIED' },
})
 
const result = validateEnvelope(envelope)
if (!result.ok) throw new Error(result.error)
// result.value is a type-safe PreparedEnvelope

Helpers and constants

The *Schema exports (evmTxEnvelopeSchema, evmBatchEnvelopeSchema, signatureEnvelopeSchema, originSchema, metadataSchema, etc.) let consumers compose custom validators.

EnvelopeCommon (the second arg to all factories) accepts { id?, issuedAt?, expiresAt?, nonce?, producer?, origin?, capabilities?, meta? }. To stamp risk (optional risk-assessment slot), set it on the returned envelope after construction - the factory does not pipe it.

Examples in the repo

Three end-to-end examples live in packages/tx-protocol/examples/ (run with pnpm exec tsx packages/tx-protocol/examples/<file>.ts):