action-patterns

name

action-patterns

description

This skill should be used when understanding how @1sat/actions work — the action/context pattern, two-phase signing (createAction/signAction), BEEF resolution, the action registry, baskets and tags. Triggers on 'createContext', 'action.execute', 'createAction', 'signAction', 'sign transaction', 'inputBEEF', 'completeSignedAction', 'action registry', 'baskets', 'tags', or 'BRC-100'. Uses @1sat/actions.

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.

inputBEEF: When Required vs Optional

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

• Optional for inputs from your own wallet — actions auto-resolve BEEF via the output's ID tag (resolveBeef fallback).
• Required for external inputs not in your wallet — e.g. purchasing a listing from another user. The buyer's wallet has no BEEF for the seller's ordlock UTXO, so the marketplace/overlay must provide it.

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: 'ordinals',
    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:

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

Category	Action	Services	Purpose
addresses	deriveDepositAddresses		Derive P1SAT deposit addresses for receiving payments, ordinals, or tokens
collections	mintCollection		Create a new ordinals collection with traits, rarity labels, and royalty configuration
collections	mintCollectionItem		Create a collection item inscription linked to a parent collection via collectionId
identity	attest		Publish a BAP attestation signed with BAP identity
identity	getProfile		Read current BAP identity profile from wallet
identity	publishIdentity		Publish initial BAP identity record from wallet
identity	rotateIdentity		Rotate BAP signing key to the next derived key
identity	updateProfile		Update BAP identity profile signed with BAP identity
inscriptions	inscribe		Create a new inscription with the given content and type
locks	getLockData		Get summary of time-locked BSV (total, unlockable, next unlock height)
locks	lockBsv		Lock BSV until a specific block height
locks	unlockBsv		Unlock all matured time-locked BSV
opns	getOpnsNames		Get OpNS names from the wallet with BEEF for spending
opns	opnsDeregister		Remove identity key binding from an OpNS name
opns	opnsRegister	✓	Register identity key on an OpNS name via MAP metadata
ordinals	burnOrdinals		Burn one or more ordinals by sending to OP_RETURN
ordinals	cancelListing		Cancel an ordinal listing and return the ordinal to the wallet
ordinals	getOrdinals		Get ordinals/inscriptions from the wallet with BEEF for spending
ordinals	listOrdinal		List an ordinal for sale on the global orderbook
ordinals	purchaseOrdinal	✓	Purchase an ordinal from the global orderbook
ordinals	transferOrdinals		Transfer one or more ordinals to new owners
payments	getMneeBalance	✓	Get MNEE stablecoin balance across yours wallet addresses
payments	getMneeConfig	✓	Get MNEE service configuration including cosigner and fee structure
payments	getMneeHistory	✓	Get MNEE transaction history with parsed amounts and counterparties
payments	getMneeTxStatus	✓	Get the status of an MNEE transfer
payments	getMneeUtxos	✓	Get MNEE UTXOs across yours wallet addresses
payments	sendAllBsv		Send all BSV from wallet to a single destination address
payments	sendBsv		Send BSV to one or more destinations (addresses, scripts, or OP_RETURN)
payments	sendMnee	✓	Send MNEE stablecoin to one or more recipients
signing	decryptFromCounterparty		Decrypt data from a counterparty using Type-42 key derivation
signing	encryptForCounterparty		Encrypt data for a counterparty using Type-42 key derivation
signing	getAuthToken		Generate a BRC-77 auth token for HTTP request signing
signing	getFriendPublicKey		Derive a public key for a counterparty using Type-42 key derivation
signing	signBsm		Sign a message using BSM (Bitcoin Signed Message) format
social	createSocialPost		Create an on-chain social post signed with BAP identity
sweep	sweepBsv	✓	Sweep BSV from external wallet (via WIF) into the connected wallet
sweep	sweepBsv21	✓	Sweep BSV-21 tokens from external wallet (via WIF) into the connected wallet
sweep	sweepOrdinals	✓	Sweep ordinals from external wallet (via WIF) into the connected wallet
sync	syncAddresses	✓	Sync external payments to BRC-29 deposit addresses into the wallet
sync	syncCosignDeliveries	✓	Pull cosign-wrapped BSV21 deliveries from a MessageBox and internalize them into the wallet
sync	syncMessages	✓	Sync incoming paymail payments from the message box into the wallet
tokens	deployBsv21Auth		Deploy a new BSV21 token with mintable supply via auth UTXOs (deploy+auth)
tokens	deployBsv21Mint		Deploy a new BSV21 token with fixed supply (deploy+mint)
tokens	getBsv21Balances		Get aggregated BSV21 token balances grouped by token ID
tokens	listTokens		List BSV21 token outputs from the wallet
tokens	mintBsv21	✓	Spend an auth UTXO to mint new supply and/or re-issue authority
tokens	purchaseBsv21	✓	Purchase BSV21 tokens from the marketplace
tokens	sendBsv21		Send BSV21 tokens to one or more recipients

Baskets and Tags

The wallet organizes outputs into baskets:

Basket	Contents
ordinals	Ordinal inscriptions (NFTs)
bsv21	BSV-21 fungible tokens
bsocial	Social protocol outputs (posts, likes, follows)
locks	Time-locked BSV
opns	OpNS name ordinals
bap	BAP identity outputs

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: 'ordinals',
  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
• 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