# Run the vectors in TypeScript

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Run the BRC-100 test vectors with the Jest runner in ts-stack, first against the reference wallet, then against a wallet of your choice.

Run the BRC-100 (BSV 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:

**1. 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:

```bash 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
```

**2. Install the runner dependencies**

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

```bash 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:

```text 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.

**3. Check the vector files**

Point the structural runner at the BRC-100 folder:

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

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

```text 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/`.

**4. 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`:

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

The build ends with the toolbox:

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

**5. Run the BRC-100 vectors**

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

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

Jest prints its summary:

```text 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`:

**1. 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:

```ts 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.

**2. Run the vectors on the new wallet**

Repeat the command of the reference run:

```bash 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:

```text 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 key (A 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.

**3. 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:

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

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

```ts 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:

```text 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`.

## Related articles

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

- [Test BRC-100 conformance](https://bsvblockchain.com/docs/wallet-dev/conformance/)
- [Browse the test vectors](https://bsvblockchain.com/docs/wallet-dev/conformance/vector-catalog/)
- [How the toolbox tracks UTXOs](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/utxo-lifecycle/)