matrix.json

{
  "schemaVersion": 1,
  "package": "@wraith-protocol/sdk",
  "engines": {
    "node": ">=20"
  },
  "runtimes": [
    {
      "id": "node",
      "name": "Node.js",
      "versions": "20.x, 22.x, 24.x",
      "minimumRange": ">=20",
      "status": "supported",
      "check": "node",
      "notes": "Covered by the `compat` CI job on every version and by the full Vitest suite. 20.x is upstream EOL (2026-04-30) and is retained for the 2.x line; 22.x is in maintenance and 24.x is the active LTS."
    },
    {
      "id": "bun",
      "name": "Bun",
      "versions": "1.1+",
      "minimumRange": ">=1.1",
      "status": "supported",
      "check": "bun",
      "notes": "Covered by the `compat` CI job. The ESM entry points, the Vitest suite (`bun test`) and the build all run unmodified."
    },
    {
      "id": "browser",
      "name": "Browsers (evergreen)",
      "versions": "Chrome 94+, Edge 94+, Firefox 93+, Safari 15.4+",
      "minimumRange": null,
      "status": "supported",
      "check": "browser",
      "notes": "Baseline is ES2022 plus `fetch`, `TextEncoder`/`TextDecoder` and `crypto.getRandomValues`; `./vault` additionally needs `crypto.subtle`. Optional peers are the app bundler's responsibility."
    },
    {
      "id": "react-native",
      "name": "React Native",
      "versions": "0.72+ (Hermes), Expo SDK 51+",
      "minimumRange": null,
      "status": "supported",
      "check": "react-native",
      "notes": "Needs a `crypto.getRandomValues` polyfill (`react-native-get-random-values`) loaded before the SDK, plus `Buffer` if the app imports `@stellar/stellar-sdk` directly. `installReactNativePolyfills()` covers `atob`, `btoa`, `TextEncoder` and `TextDecoder`."
    },
    {
      "id": "deno",
      "name": "Deno",
      "versions": "2.x",
      "minimumRange": null,
      "status": "partial",
      "check": null,
      "notes": "Use npm specifiers. Verified by static review only — the compat job does not provision a Deno runtime yet."
    },
    {
      "id": "edge",
      "name": "Cloudflare Workers / Vercel Edge",
      "versions": "current",
      "minimumRange": null,
      "status": "partial",
      "check": null,
      "notes": "The browser bundle check covers the same module graph. Optional peers must be bundled explicitly when the edge entry point you use needs them."
    }
  ],
  "peers": [
    {
      "name": "@stellar/stellar-sdk",
      "kind": "peer",
      "optional": true,
      "range": "^13.1.0",
      "requiredBy": ["./chains/stellar"],
      "requiredAtImport": ["./chains/stellar"],
      "tested": ["13.3.0"],
      "notes": "Required by `./chains/stellar`: the transaction builders, event filters and announcement parsing are re-exported from that entry point. Marked optional so apps that only use the EVM, CKB, Solana or vault entry points are not forced to install it."
    },
    {
      "name": "@solana/web3.js",
      "kind": "peer",
      "optional": true,
      "range": "^1.95.0",
      "requiredBy": ["./chains/solana"],
      "requiredAtImport": [],
      "tested": ["1.98.4"],
      "notes": "Only `fetchAnnouncements()` needs it, and it imports the package dynamically on demand. Address derivation and scanning use the in-tree base58 encoder, so importing `./chains/solana` — or the package root — works without this peer installed."
    },
    {
      "name": "viem",
      "kind": "dependency",
      "optional": false,
      "range": "^2.23.0",
      "requiredBy": [".", "./chains/evm", "./chains/ckb"],
      "requiredAtImport": [".", "./chains/evm", "./chains/ckb"],
      "tested": ["2.47.14"],
      "notes": "A regular dependency, not a peer: the EVM and CKB modules use its hex and keccak helpers, and the wallet event normalizer uses `getAddress`. Bundled with the package, so consumers never install it separately."
    }
  ],
  "unsupported": [
    {
      "combination": "Node.js 18 and older",
      "failure": "Unsupported runtime: Node.js 18.x. @wraith-protocol/sdk requires Node.js >=20 (see package.json engines). See COMPAT.md for the supported matrix."
    },
    {
      "combination": "Bun 1.0 and older",
      "failure": "Unsupported runtime: Bun 1.0.x. @wraith-protocol/sdk requires Bun >=1.1. See COMPAT.md for the supported matrix."
    },
    {
      "combination": "React Native without a crypto.getRandomValues polyfill",
      "failure": "React Native requires a crypto polyfill. Install and import react-native-get-random-values before using @wraith-protocol/sdk."
    },
    {
      "combination": "Browsers or edge runtimes without WebCrypto, when using ./vault",
      "failure": "KeyVault requires WebCrypto (crypto.subtle)."
    },
    {
      "combination": "./chains/stellar without @stellar/stellar-sdk installed",
      "failure": "Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@stellar/stellar-sdk' imported from @wraith-protocol/sdk/chains/stellar."
    },
    {
      "combination": "fetchAnnouncements() from ./chains/solana without @solana/web3.js installed",
      "failure": "Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@solana/web3.js' imported from @wraith-protocol/sdk/chains/solana."
    },
    {
      "combination": "Installing on a Node.js version below the declared engines range",
      "failure": "npm ERR! code EBADENGINE\nnpm ERR! engine Unsupported engine\nnpm ERR! engine Not compatible with your version of node/npm: @wraith-protocol/sdk@1.x\nnpm ERR! notsup Required: {\"node\":\">=20\"}"
    },
    {
      "combination": "TypeScript below 4.7 with node16 or bundler module resolution",
      "failure": "Cannot find module '@wraith-protocol/sdk/chains/evm' or its corresponding type declarations."
    }
  ]
}