Action Patterns

Action Patterns

The shared mechanics behind every @1sat/actions operation: the action/context pattern, two-phase signing, BEEF resolution, the registry, and baskets/tags. For a specific operation, jump to the domain skill (pointers below).

The Action System

Every operation is an Action with meta (name, description, category, input schema) and an execute(ctx, input) method:

createContext(wallet, { services }) → action.execute(ctx, input) → { txid, tx, error }

Actions work with any BRC-100 compatible wallet (OneSatWallet, browser extension, wallet-remote, etc).

Context Setup

createContext takes the wallet positionally and an options object second:

import { createContext } from '@1sat/actions'

// Wallet only
const ctx = createContext(wallet)

// Wallet + services (for network operations) and other options
const ctx = createContext(wallet, {
  services,        // OneSatServices for network-dependent actions
  chain: 'main',   // 'main' | 'test' (default 'main')
  debug: true,     // emit derivation logs for fund recovery
})

Actions whose meta.requiresServices is true need services in the context.

Running an Action

import { createContext, sendBsv } from '@1sat/actions'

const ctx = createContext(wallet, { services })
const result = await sendBsv.execute(ctx, {
  requests: [{ address: '1Recipient...', satoshis: 50000 }],
})

All transaction-producing actions return tx?: number[] (AtomicBEEF), not hex strings.

The Two-Phase Signing Pattern

Operations that spend custom scripts (ordinals, locks, tokens) build the transaction first, then sign it in a second phase. Single-phase plain sends (sendBsv/sendAllBsv) skip this entirely.

Id-first P1SAT assets

Wallet-owned non-fungible assets (OpNS, ordinals, locks) use id: tags in their domain basket.

• Spend (owned): pass { id } only. Action loads the row + BEEF via loadBasketOutputBeef(basket, id). Do not pass a stale WalletOutput as the source of truth.
• Self-move filing: ordinalSeedTags(output) + fixed domain basket + action-specific tags. Do not use resolveOrdinalTags for owned assets.
• List/read: tags/CI on by default; BEEF off unless include: 'entire transactions'.
• External spend (buy): { outpoint, inputBEEF? } — BEEF if provided, else services fetch, else error. Plus path-specific fields.
• Fungible (BSV21): value API (tokenId, amounts); internal UTXOs still have id:; self destinations must stay basketed.

Helpers: loadBasketOutput / loadBasketOutputBeef, ordinalSeedTags, toIdTag.

inputBEEF: When Required vs Optional

inputBEEF provides the SPV proof chain for the inputs being spent:

• Owned id-first paths: caller usually omits BEEF — action loads it from the basket by id.
• External inputs: pass inputBEEF or rely on services fetch (buy paths). Wallet has no proof for foreign UTXOs.

Phase 1: createAction (build the transaction)

const createResult = await wallet.createAction({
  description: 'Transfer ordinal',
  inputBEEF: beefData,          // optional for wallet-owned inputs, required for external
  inputs: [{
    outpoint: 'txid.vout',
    inputDescription: 'Ordinal to transfer',
    unlockingScriptLength: 108, // expected script size
  }],
  outputs: [{
    lockingScript: '76a914...88ac',
    satoshis: 1,
    outputDescription: 'Transferred ordinal',
    basket: '1sat',
    tags: ['type:image/png', 'origin:abc...'],
    customInstructions: JSON.stringify({ protocolID, keyID }),
  }],
  options: {
    signAndProcess: false,      // don't auto-sign yet
    randomizeOutputs: false,    // preserve output order
  },
})

Phase 2: completeSignedAction (sign and finalize)

Use the completeSignedAction helper for all two-phase actions. It handles BEEF merge (fixing stripped merkle proofs), script verification, signAction, and automatic abortAction on failure.

import { completeSignedAction } from '@1sat/actions'

const result = await completeSignedAction(
  wallet,
  createResult,           // from createAction with signAndProcess: false
  inputBEEF as number[],  // BEEF from listOutputs (has full SPV proof chain)
  async (tx) => {
    // tx is a fully-wired Transaction ready for signing.
    // Return unlocking scripts keyed by input index.
    const spends: Record<number, { unlockingScript: string }> = {}
    spends[0] = { unlockingScript: myUnlockingScript.toHex() }
    return spends
  },
)

// result.txid is the broadcast transaction ID

Why not raw signAction? The signable transaction BEEF from createAction has merkle proofs stripped (wallet-toolbox uses mergeRawTx internally, raw txs only, no bumps). completeSignedAction merges the unsigned tx back into inputBEEF to reconstruct the full proof chain before signing. It also verifies unlocking scripts against locking scripts before submitting, and aborts the action automatically if signing fails.

Action Registry

All actions are registered in a global registry:

import { actionRegistry } from '@1sat/actions'

// List all registered actions
for (const action of actionRegistry.list()) {
  console.log(`${action.meta.name} (${action.meta.category})`)
}

// Get a specific action
const send = actionRegistry.get('sendBsv')

// Convert to MCP tool definitions
const tools = actionRegistry.toMcpTools()

The complete, generated list of all actions:

54 actions, generated from the registry — do not edit by hand.

Baskets and Tags

The wallet organizes outputs into baskets:

Storage baskets are plain names. p 1sat … is not a basket: createAction uses labels (p <scheme> action, p <scheme> input id <key>); listOutputs view grants are p 1sat all|collection|app|creator|id (rewritten to 1sat).

Tags on outputs provide metadata for filtering and for the ID-tag BEEF resolution used by two-phase actions:

const result = await wallet.listOutputs({
  basket: '1sat',
  includeTags: true,
  includeCustomInstructions: true,
  include: 'entire transactions', // include BEEF for spending
  limit: 100,
})

Domain Skills

Per-operation detail lives in sibling skills, not here:

• Sending BSV, batch payments, OP_RETURN, deposit addresses: see ../payments
• Inscriptions: see ../inscriptions
• Ordinals (transfer, list, purchase): see ../ordinals
• Tokens (deploy, mint, send, burn): see ../tokens
• Locks: see ../locks
• Permission module (host WPM, view scopes): see ../../../permission-module/skills/permission-module
• Message signing (BSM): see ../signing
• BAP identity (publish, profile, attest): see ../identity
• Social posts: see ../social
• OpNS: see ../opns
• Sweep: see ../sweep

Low-Level Custom Building

For truly low-level, custom transaction construction outside the action system, @1sat/core (TxBuilder, protocol helpers) and @1sat/templates (Inscription, OrdP2PKH, OrdLock, Lock, BSV20, BSV21 script templates) are available. Note: token deploy/mint/burn and ordinal operations now have first-class actions — use ../tokens and ../ordinals rather than dropping to @1sat/core for those.

Requirements

bun add @1sat/actions @bsv/sdk