Conformance Testing

The TypeScript stack is the reference source for portable BSV behavior. The conformance corpus turns that behavior into language-neutral JSON fixtures that SDKs, wallets, and infrastructure clients can reuse.

The current corpus totals are generated from conformance/META.json and the parity matrix on the Generated Stack Facts page. CI rejects drift between those sources and the 74 JSON vector files.

How It Works

1. A protocol behavior is captured as a JSON vector under conformance/vectors/.
2. The vector records deterministic inputs and expected outputs.
3. The structural runner validates that vector files are well formed and emits reports.
4. The TypeScript/Jest runner dispatches supported vectors into @bsv/sdk behavior.
5. Other implementations can read the same JSON files and compare their outputs.

Runner Entry Points

Reports from the structural runner land in conformance/runner/reports/.

Coverage

Vector Format

Each vector file uses one metadata envelope with a vectors array:

{
  "$schema": "../../../schema/vector.schema.json",
  "id": "wallet.brc100.getpublickey",
  "name": "BRC-100 WalletInterface.getPublicKey",
  "brc": ["BRC-100"],
  "version": "1.0.0",
  "reference_impl": "ts-sdk@2.0.14",
  "parity_class": "required",
  "vectors": [
    {
      "id": "wallet.brc100.getpublickey.1",
      "input": {
        "args": { "identityKey": true }
      },
      "expected": {
        "publicKey": "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"
      },
      "tags": ["happy-path", "brc-100"]
    }
  ]
}

See conformance/VECTOR-FORMAT.md and Contributing Vectors before adding new fixtures.

Testing Another Implementation

For a non-TypeScript SDK or wallet:

1. Read vector files directly from conformance/vectors/.
2. Preserve file IDs and vector IDs in your runner output.
3. Start with deterministic SDK vectors (sdk/crypto, sdk/keys) before stateful wallet vectors.
4. Compare your actual output to each vector's expected object.
5. Track unsupported categories explicitly rather than silently ignoring them.

Maintained contracts

• pnpm conformance --validate-only validates the complete structural corpus.
• pnpm docs:facts:check verifies metadata, parity classifications, and generated totals.
• pnpm test:governance owns every intended or skipped behavior with a reason, owner, review date, and removal condition.
• The TypeScript/Jest behavior runner and package suites provide executable implementation assertions; a structural pass must not be described as a behavioral pass.

Next Steps

• Vector Catalog — Current vector files and method coverage
• TypeScript Runner — Runner commands and limitations
• Contributing Vectors — Add or refine fixtures
• Architecture View — High-level overview for port planning teams
• Porting Guide — Practical guide for aligning Go, Rust, Python, or other language implementations (including known deviations and conformance tiers)