BSV blockchainBSV blockchain

Run the vectors in TypeScript

Run the BRC-100BSV Request for Comments 100, the standard interface between apps and wallets test vectors with the TypeScript runner in ts-stack, first against the reference wallet and then against another wallet. You end with a Jest summary that counts one passed test per required vector, or names each vector the wallet fails. The wallets run in memory on the test chain, with no funds involved.

Before you begin

You need Node.js 24.11 or newer and pnpm 10 or newer, the versions that the ts-stack package.json asks for. To test your own wallet in the last section, it implements WalletInterface from @bsv/sdk and can be built from a root private key. This page was written against ts-stack commit 389d5d8 of October 27, 2026, which holds @bsv/sdk 4.0.1 and @bsv/wallet-toolbox 2.15.1.

How it works

ts-stack has two runners, and only one of them calls a wallet:

  • The structural runner, pnpm conformance, parses each vector file and checks its fields. A structural pass says the files are well formed, not that a wallet behaves.
  • The Jest runner, conformance/runner/ts/runner.test.ts, creates one test per vector, named by its ID. It sends the BRC-100 files to dispatchers/wallet.ts, which builds a wallet for each vector, calls the method and compares the result with expected. Intended vectors become skipped tests that carry their reason.

The dispatcher builds two kinds of wallet. makeWallet returns a ProtoWallet from @bsv/sdk for the nine key and crypto methods. setupTestWallet returns a Wallet from @bsv/wallet-toolbox, with in-memory storage, for the action, output and certificate methods. The six wallet state methods, such as getHeight and getVersion, are checked against fixed values in the dispatcher and never reach a wallet.

Run the vectors against the reference wallet

The first run uses the wallets the dispatcher already builds, so you see a clean result before you change anything:

Clone ts-stack

Clone the repository at the commit this page was written against, then work from its root for every command on this page:

Terminal
git clone --depth 1 --no-checkout https://github.com/bsv-blockchain/ts-stack.git
cd ts-stack
git fetch --depth 1 origin 389d5d806495903ee56273978ccc7e8ab71ceb86
git checkout FETCH_HEAD

Install the runner dependencies

Install only the two runners and the workspace packages they depend on:

Terminal
pnpm install --ignore-scripts --filter "@bsv/conformance-runner-ts..." --filter "@bsv/conformance-runner" --filter "@bsv/ts-stack"

The install ends with a line such as:

Output
Done in 16.8s using pnpm v10.33.2

The ... after the package name also installs the packages it depends on, such as @bsv/sdk and @bsv/wallet-toolbox. --ignore-scripts skips native builds such as better-sqlite3, which the runner does not use because its wallets keep their records in memory.

Check the vector files

Point the structural runner at the BRC-100 folder:

Terminal
pnpm conformance --vectors conformance/vectors/wallet/brc100

After one line per file, the summary shows 28 files and 955 vectors:

Output
Summary
  Total vector files : 28
  Total vectors      : 955
  Parse/structure errors : 0

RESULT: PASS — all vector files parsed cleanly

The runner also writes a JSON and a JUnit report to conformance/runner/reports/.

Build the workspace packages

Build the packages that the Jest runner imports, such as @bsv/air-gap and @bsv/chirp. Without them, Jest stops with Cannot find module:

Terminal
pnpm --filter "@bsv/conformance-runner-ts..." --if-present build

The build ends with the toolbox:

Output
packages/wallet/wallet-toolbox build$ tsc --build
packages/wallet/wallet-toolbox build: Done

Run the BRC-100 vectors

Start the Jest runner and keep the tests whose name contains wallet.brc100:

Terminal
pnpm --filter @bsv/conformance-runner-ts test -t "wallet.brc100"

Jest prints its summary:

Output
Test Suites: 1 skipped, 1 passed, 1 of 2 total
Tests:       5904 skipped, 816 passed, 6720 total
Snapshots:   0 total
Time:        6.944 s, estimated 8 s
Ran all test suites with tests matching "wallet.brc100".

The 816 passed tests are the 816 required BRC-100 vectors. The skipped ones are the 139 intended BRC-100 vectors and the tests of other domains that -t filters out. To run one method, add its file name to the filter, for example -t "wallet.brc100.abortaction" runs the 2 required abortAction vectors.

Point the runner at another wallet

With the reference run clean, change the wallet the dispatcher builds and run the vectors again. The example below sends the key and crypto methods to the wallet-toolbox Wallet instead of ProtoWallet. Your own wallet goes in the same place. All changes are in conformance/runner/ts/dispatchers/wallet.ts:

Build every wallet in one function

The root keys in the vectors are public test values, such as key 1 written in hex. Never fund a wallet built from them and never reuse them for a real wallet.

Replace makeWallet so that it returns the wallet from setupTestWallet, built from the vector’s root key:

dispatchers/wallet.ts
async function makeWallet(input: Record<string, unknown>): Promise<WalletInterface> {
  const rootHex =
    getString(input, 'root_key') ||
    '0000000000000000000000000000000000000000000000000000000000000001'
  return await setupTestWallet(rootHex)
}

makeWallet is now async, so change each of its nine calls from const wallet = makeWallet(input) to const wallet = await makeWallet(input). From here on, setupTestWallet builds the wallet for every method that reaches one. To test your own wallet, return it from setupTestWallet, built from rootKeyHex. The expected results derive from the vector’s root key, so a wallet built from another key fails every vector that depends on it.

Run the vectors on the new wallet

Repeat the command of the reference run:

Terminal
pnpm --filter @bsv/conformance-runner-ts test -t "wallet.brc100"

Jest names each failing vector with the error the wallet threw, then the totals:

Output
  ● wallet.brc100.getpublickey › wallet.brc100.getpublickey.2

    Privileged operations require the Wallet to be configured with a privileged key manager.

Tests:       75 failed, 5904 skipped, 741 passed, 6720 total

100 getPublicKey vectors ask for a privileged keyA very sensitive private key that the wallet fetches from secure storage only for calls that set privileged to true. ProtoWallet does not handle privileged keys and derives these from its root key like any other. The toolbox Wallet needs a privileged key manager, so it fails the 75 vectors that expect a key and passes the 25 that expect an error.

Fix the wallet and run again

Give the toolbox wallet a privileged key manager in setupTestWallet. Import it at the top of the file, next to the other toolbox imports:

dispatchers/wallet.ts
import { PrivilegedKeyManager } from '@wallet-toolbox/sdk/PrivilegedKeyManager'

Then add it to the options of new Wallet in setupTestWallet:

dispatchers/wallet.ts
const wallet = new Wallet({
  chain: 'test',
  keyDeriver,
  storage,
  lookupResolver: makeStubLookupResolver(),
  privilegedKeyManager: new PrivilegedKeyManager(async () => rootKey)
})

The key getter returns the vector’s root key, which is the key the privileged vectors expect. Run the same command again, and all required vectors pass:

Output
Tests:       5904 skipped, 816 passed, 6720 total

Jest may also warn that a worker process failed to exit gracefully. The warning does not change the result.

The six wallet state dispatchers still check fixed values, so their 33 passes say nothing about the wallet under test until those dispatchers call it.

Troubleshooting

Test script fails on Windows #

The test script sets NODE_OPTIONS inline, which the Windows command prompt cannot run, so pnpm stops with 'NODE_OPTIONS' is not recognized as an internal or external command. Run the script through Git Bash with pnpm --config.script-shell="C:\Program Files\Git\usr\bin\bash.exe" --filter @bsv/conformance-runner-ts test -t "wallet.brc100".

Build fails with a SHA-256 mismatch #

The build of @bsv/verifast checks the hash of its files and stops with bdk-core.mjs SHA-256 mismatch when Git converted their line endings at checkout, which happens on Windows with core.autocrlf set to true. Clone again with the conversion off: git clone -c core.autocrlf=false --depth 1 --no-checkout https://github.com/bsv-blockchain/ts-stack.git && cd ts-stack && git fetch --depth 1 origin 389d5d806495903ee56273978ccc7e8ab71ceb86 && git checkout FETCH_HEAD.

To learn more about BRC-100 conformance on the BSV blockchain, review these articles: