@txnod/sdk 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/AGENTS.md +29 -0
  2. package/CHANGELOG.md +22 -0
  3. package/LICENSE +21 -0
  4. package/README.md +434 -0
  5. package/dist/_shared/index.d.ts +68 -0
  6. package/dist/client-sandbox.d.ts +396 -0
  7. package/dist/client-sandbox.d.ts.map +1 -0
  8. package/dist/client-sandbox.js +448 -0
  9. package/dist/client-sandbox.js.map +1 -0
  10. package/dist/client.d.ts +429 -0
  11. package/dist/client.d.ts.map +1 -0
  12. package/dist/client.js +588 -0
  13. package/dist/client.js.map +1 -0
  14. package/dist/env.d.ts +29 -0
  15. package/dist/env.d.ts.map +1 -0
  16. package/dist/env.js +44 -0
  17. package/dist/env.js.map +1 -0
  18. package/dist/errors.d.ts +1887 -0
  19. package/dist/errors.d.ts.map +1 -0
  20. package/dist/errors.js +2107 -0
  21. package/dist/errors.js.map +1 -0
  22. package/dist/index.d.ts +35 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +32 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/internals/error-ctor-map.d.ts +11 -0
  27. package/dist/internals/error-ctor-map.d.ts.map +1 -0
  28. package/dist/internals/error-ctor-map.js +75 -0
  29. package/dist/internals/error-ctor-map.js.map +1 -0
  30. package/dist/internals/fetch-with-retry.d.ts +34 -0
  31. package/dist/internals/fetch-with-retry.d.ts.map +1 -0
  32. package/dist/internals/fetch-with-retry.js +233 -0
  33. package/dist/internals/fetch-with-retry.js.map +1 -0
  34. package/dist/internals/hmac.d.ts +2 -0
  35. package/dist/internals/hmac.d.ts.map +1 -0
  36. package/dist/internals/hmac.js +10 -0
  37. package/dist/internals/hmac.js.map +1 -0
  38. package/dist/internals/logger.d.ts +9 -0
  39. package/dist/internals/logger.d.ts.map +1 -0
  40. package/dist/internals/logger.js +16 -0
  41. package/dist/internals/logger.js.map +1 -0
  42. package/dist/internals/parse-problem-details.d.ts +3 -0
  43. package/dist/internals/parse-problem-details.d.ts.map +1 -0
  44. package/dist/internals/parse-problem-details.js +76 -0
  45. package/dist/internals/parse-problem-details.js.map +1 -0
  46. package/dist/internals/synthetic-details.d.ts +12 -0
  47. package/dist/internals/synthetic-details.d.ts.map +1 -0
  48. package/dist/internals/synthetic-details.js +19 -0
  49. package/dist/internals/synthetic-details.js.map +1 -0
  50. package/dist/verify/chains/bsc.d.ts +17 -0
  51. package/dist/verify/chains/bsc.d.ts.map +1 -0
  52. package/dist/verify/chains/bsc.js +15 -0
  53. package/dist/verify/chains/bsc.js.map +1 -0
  54. package/dist/verify/chains/btc.d.ts +22 -0
  55. package/dist/verify/chains/btc.d.ts.map +1 -0
  56. package/dist/verify/chains/btc.js +55 -0
  57. package/dist/verify/chains/btc.js.map +1 -0
  58. package/dist/verify/chains/cardano.d.ts +73 -0
  59. package/dist/verify/chains/cardano.d.ts.map +1 -0
  60. package/dist/verify/chains/cardano.js +175 -0
  61. package/dist/verify/chains/cardano.js.map +1 -0
  62. package/dist/verify/chains/evm.d.ts +21 -0
  63. package/dist/verify/chains/evm.d.ts.map +1 -0
  64. package/dist/verify/chains/evm.js +46 -0
  65. package/dist/verify/chains/evm.js.map +1 -0
  66. package/dist/verify/chains/polygon.d.ts +17 -0
  67. package/dist/verify/chains/polygon.d.ts.map +1 -0
  68. package/dist/verify/chains/polygon.js +15 -0
  69. package/dist/verify/chains/polygon.js.map +1 -0
  70. package/dist/verify/chains/secp256k1-bip32.d.ts +20 -0
  71. package/dist/verify/chains/secp256k1-bip32.d.ts.map +1 -0
  72. package/dist/verify/chains/secp256k1-bip32.js +88 -0
  73. package/dist/verify/chains/secp256k1-bip32.js.map +1 -0
  74. package/dist/verify/chains/ton-cell.d.ts +179 -0
  75. package/dist/verify/chains/ton-cell.d.ts.map +1 -0
  76. package/dist/verify/chains/ton-cell.js +614 -0
  77. package/dist/verify/chains/ton-cell.js.map +1 -0
  78. package/dist/verify/chains/ton.d.ts +84 -0
  79. package/dist/verify/chains/ton.d.ts.map +1 -0
  80. package/dist/verify/chains/ton.js +131 -0
  81. package/dist/verify/chains/ton.js.map +1 -0
  82. package/dist/verify/chains/tron.d.ts +21 -0
  83. package/dist/verify/chains/tron.d.ts.map +1 -0
  84. package/dist/verify/chains/tron.js +42 -0
  85. package/dist/verify/chains/tron.js.map +1 -0
  86. package/dist/verify/config.d.ts +41 -0
  87. package/dist/verify/config.d.ts.map +1 -0
  88. package/dist/verify/config.js +120 -0
  89. package/dist/verify/config.js.map +1 -0
  90. package/dist/verify/errors.d.ts +56 -0
  91. package/dist/verify/errors.d.ts.map +1 -0
  92. package/dist/verify/errors.js +58 -0
  93. package/dist/verify/errors.js.map +1 -0
  94. package/dist/verify/index.d.ts +119 -0
  95. package/dist/verify/index.d.ts.map +1 -0
  96. package/dist/verify/index.js +166 -0
  97. package/dist/verify/index.js.map +1 -0
  98. package/dist/verify/xpub-safety.d.ts +33 -0
  99. package/dist/verify/xpub-safety.d.ts.map +1 -0
  100. package/dist/verify/xpub-safety.js +54 -0
  101. package/dist/verify/xpub-safety.js.map +1 -0
  102. package/dist/verify-webhook-signature.d.ts +30 -0
  103. package/dist/verify-webhook-signature.d.ts.map +1 -0
  104. package/dist/verify-webhook-signature.js +84 -0
  105. package/dist/verify-webhook-signature.js.map +1 -0
  106. package/docs/00-getting-started.md +135 -0
  107. package/docs/01-authentication.md +114 -0
  108. package/docs/02-invoices.md +216 -0
  109. package/docs/03-rates-and-quotes.md +82 -0
  110. package/docs/04-webhooks.md +126 -0
  111. package/docs/05-errors.md +199 -0
  112. package/docs/05-sandbox.md +159 -0
  113. package/docs/06-idempotency.md +132 -0
  114. package/docs/examples/express-webhook-receiver.md +97 -0
  115. package/docs/examples/nextjs-route-handler.md +206 -0
  116. package/docs/examples/sandbox-vitest-suite.md +263 -0
  117. package/docs/index.md +66 -0
  118. package/docs/reference/client.md +392 -0
  119. package/docs/reference/errors.md +161 -0
  120. package/docs/reference/types.md +400 -0
  121. package/package.json +53 -0
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Shared secp256k1 BIP-32 derivation core for BTC / EVM / TRON / Polygon / BSC.
3
+ * Cardano (Ed25519 + CIP-1852) lives in chains/cardano.ts (Story 25.4).
4
+ * Cross-checked byte-for-byte against server-side derivation in
5
+ * apps/web/lib/derivation/{btc,evm,tron}.ts (Story 25.3 AC 9 fixture vectors).
6
+ *
7
+ * Sources:
8
+ * - PRD FR96: SDK locally verifies createInvoice address derives from xpub.
9
+ * - Architecture addendum §4.1 (SDK directory layout).
10
+ * - Discovery §C.6 (Paul Miller / @noble / @scure family rationale),
11
+ * §E.1 (path 3 — audited deps + CI guard).
12
+ * - BIP-32 (https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).
13
+ */
14
+ export interface DeriveSecp256k1ChildPubkeyInput {
15
+ xpub: string;
16
+ derivation_path: string;
17
+ }
18
+ /** Returns the 33-byte compressed secp256k1 public key at the leaf. */
19
+ export declare function deriveSecp256k1ChildPubkey(input: DeriveSecp256k1ChildPubkeyInput): Uint8Array;
20
+ //# sourceMappingURL=secp256k1-bip32.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secp256k1-bip32.d.ts","sourceRoot":"","sources":["../../../src/verify/chains/secp256k1-bip32.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8DH,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD,uEAAuE;AACvE,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,UAAU,CA4BZ"}
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Shared secp256k1 BIP-32 derivation core for BTC / EVM / TRON / Polygon / BSC.
3
+ * Cardano (Ed25519 + CIP-1852) lives in chains/cardano.ts (Story 25.4).
4
+ * Cross-checked byte-for-byte against server-side derivation in
5
+ * apps/web/lib/derivation/{btc,evm,tron}.ts (Story 25.3 AC 9 fixture vectors).
6
+ *
7
+ * Sources:
8
+ * - PRD FR96: SDK locally verifies createInvoice address derives from xpub.
9
+ * - Architecture addendum §4.1 (SDK directory layout).
10
+ * - Discovery §C.6 (Paul Miller / @noble / @scure family rationale),
11
+ * §E.1 (path 3 — audited deps + CI guard).
12
+ * - BIP-32 (https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).
13
+ */
14
+ import { HDKey } from '@scure/bip32';
15
+ import { sha256 } from '@noble/hashes/sha2.js';
16
+ import { createBase58check } from '@scure/base';
17
+ import { TxnodInvalidXpubFormatError } from '../../errors.js';
18
+ import { syntheticDetails } from '../../internals/synthetic-details.js';
19
+ const b58check = createBase58check(sha256);
20
+ const XPUB_VERSION_MAINNET = new Uint8Array([0x04, 0x88, 0xb2, 0x1e]);
21
+ // Allowlist of accepted **public** extended-key version bytes — must match
22
+ // `packages/shared/src/wallets/xpub-reencode.ts` byte-for-byte.
23
+ const ALLOWED_VERSIONS = new Set([
24
+ 0x0488b21e, // xpub
25
+ 0x043587cf, // tpub
26
+ 0x04b24746, // zpub
27
+ 0x045f1cf6, // vpub
28
+ ]);
29
+ const EXTENDED_KEY_BYTE_LENGTH = 78;
30
+ const VERSION_BYTE_LENGTH = 4;
31
+ /**
32
+ * Strip the BIP-32 version prefix from any 78-byte extended key (xpub /
33
+ * tpub / zpub / vpub) and re-prepend mainnet xpub `0x0488B21E`. The 74-byte
34
+ * payload is identical regardless of version envelope, so the derived
35
+ * pubkey bytes are unchanged. This dodges `@scure/bip32@2`'s strict
36
+ * `BITCOIN_VERSIONS` check that otherwise rejects testnet variants with
37
+ * "Version mismatch". Address-encoding (which IS network-sensitive for
38
+ * BTC) lives downstream in `chains/btc.ts` and is unaffected.
39
+ *
40
+ * Inline copy by design — `packages/sdk` MUST NOT take a runtime dependency
41
+ * on `@txnod/shared` (zero-dep / dep-allowlist policy). Canonical source:
42
+ * `packages/shared/src/wallets/xpub-reencode.ts` — keep the two in sync.
43
+ */
44
+ function reencodeAsMainnetXpub(extended) {
45
+ const decoded = b58check.decode(extended);
46
+ if (decoded.length !== EXTENDED_KEY_BYTE_LENGTH) {
47
+ throw pathError(`xpub: expected ${EXTENDED_KEY_BYTE_LENGTH}-byte BIP-32 payload, got ${decoded.length} bytes`);
48
+ }
49
+ const version = (decoded[0] << 24) |
50
+ (decoded[1] << 16) |
51
+ (decoded[2] << 8) |
52
+ decoded[3];
53
+ if (!ALLOWED_VERSIONS.has(version >>> 0)) {
54
+ throw pathError(`xpub: unsupported version bytes 0x${version
55
+ .toString(16)
56
+ .padStart(8, '0')} (expected xpub/tpub/zpub/vpub)`);
57
+ }
58
+ const body = decoded.slice(VERSION_BYTE_LENGTH);
59
+ const reencoded = new Uint8Array(XPUB_VERSION_MAINNET.length + body.length);
60
+ reencoded.set(XPUB_VERSION_MAINNET, 0);
61
+ reencoded.set(body, XPUB_VERSION_MAINNET.length);
62
+ return b58check.encode(reencoded);
63
+ }
64
+ function pathError(message) {
65
+ return new TxnodInvalidXpubFormatError(syntheticDetails('invalid_xpub_format', 400, message));
66
+ }
67
+ /** Returns the 33-byte compressed secp256k1 public key at the leaf. */
68
+ export function deriveSecp256k1ChildPubkey(input) {
69
+ const segments = input.derivation_path.split('/');
70
+ if (segments.length < 3 || segments[0] !== 'm') {
71
+ throw pathError(`derivation_path '${input.derivation_path}' must begin with 'm' and have at least 2 segments after 'm'.`);
72
+ }
73
+ const change = segments[segments.length - 2] ?? '';
74
+ const index = segments[segments.length - 1] ?? '';
75
+ if (change.endsWith("'") || index.endsWith("'")) {
76
+ throw pathError(`derivation_path '${input.derivation_path}' last two segments must be non-hardened (no apostrophe suffix).`);
77
+ }
78
+ if (!/^\d+$/.test(change) || !/^\d+$/.test(index)) {
79
+ throw pathError(`derivation_path '${input.derivation_path}' last two segments must be unsigned integers.`);
80
+ }
81
+ const node = HDKey.fromExtendedKey(reencodeAsMainnetXpub(input.xpub));
82
+ const child = node.derive(`m/${change}/${index}`);
83
+ if (child.publicKey === null) {
84
+ throw pathError(`derivation_path '${input.derivation_path}' produced a null publicKey (unexpected for non-hardened public derivation).`);
85
+ }
86
+ return child.publicKey;
87
+ }
88
+ //# sourceMappingURL=secp256k1-bip32.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secp256k1-bip32.js","sourceRoot":"","sources":["../../../src/verify/chains/secp256k1-bip32.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,179 @@
1
+ /** Minimal cell record. Ordinary cells only — exotic types are out of scope. */
2
+ export interface Cell {
3
+ readonly bits: Uint8Array;
4
+ readonly bitLen: number;
5
+ readonly refs: readonly Cell[];
6
+ readonly depth: number;
7
+ readonly hash: Uint8Array;
8
+ }
9
+ /**
10
+ * Parse either raw `<workchain>:<hex64>` or user-friendly base64/base64url
11
+ * (EQ/UQ/kQ/0Q…) into a normalised account record.
12
+ *
13
+ * @source github.com/ton-org/ton-core/src/address/Address.ts — `parseRaw` /
14
+ * `parseFriendly` semantics; rejects malformed input via plain `Error`.
15
+ */
16
+ export declare function parseAddress(input: string): {
17
+ workchain: number;
18
+ hex: string;
19
+ bounceable: boolean;
20
+ testOnly: boolean;
21
+ };
22
+ /**
23
+ * Encode a parsed account in user-friendly base64url form. Tag byte is
24
+ * `0x11` (bounceable) / `0x51` (non-bounceable), OR'd with `0x80` for testnet.
25
+ *
26
+ * @source github.com/ton-org/ton-core/src/address/Address.ts — `toString`
27
+ * with `urlSafe: true`.
28
+ */
29
+ export declare function serializeAddressUserFriendly(parts: {
30
+ workchain: number;
31
+ hex: string;
32
+ }, opts: {
33
+ bounceable: boolean;
34
+ testOnly: boolean;
35
+ }): string;
36
+ /** Lowercase `<workchain>:<hex64>` raw form. */
37
+ export declare function serializeAddressRaw(parts: {
38
+ workchain: number;
39
+ hex: string;
40
+ }): string;
41
+ /**
42
+ * Parse-then-compare on raw form. EQ… / UQ… / kQ… / 0Q… all collapse to the
43
+ * same `(workchain, hex)` tuple per AR-TON-4 + research §4.9.4.
44
+ */
45
+ export declare function addressEquals(a: string, b: string): boolean;
46
+ /** Tiny chainable cell builder narrowed to the address-derivation surface. */
47
+ export interface CellBuilder {
48
+ storeUint(value: number | bigint, bits: number): CellBuilder;
49
+ storeInt(value: number | bigint, bits: number): CellBuilder;
50
+ storeBit(value: 0 | 1 | boolean): CellBuilder;
51
+ storeBuffer(buf: Uint8Array): CellBuilder;
52
+ storeRef(cell: Cell): CellBuilder;
53
+ storeAddress(parts: {
54
+ workchain: number;
55
+ hex: string;
56
+ }): CellBuilder;
57
+ endCell(): Cell;
58
+ }
59
+ /**
60
+ * @source github.com/ton-org/ton-core/src/boc/Builder.ts — `beginCell()` /
61
+ * `Builder` write-side primitives only.
62
+ */
63
+ export declare function beginCell(): CellBuilder;
64
+ /** 32-byte representation hash per TVM spec (level 0, no exotic). */
65
+ export declare function cellHash(cell: Cell): Uint8Array;
66
+ /**
67
+ * Slice cursor over a Cell — read pointer-style consumption of bits and refs
68
+ * without mutating the source. Narrowed to the read primitives the jetton
69
+ * decoder needs.
70
+ *
71
+ * @source github.com/ton-org/ton-core/src/boc/Slice.ts — read-side primitives
72
+ * only; matches the consumer/producer contract used by `beginCell()`.
73
+ */
74
+ export interface CellSlice {
75
+ /** Bits remaining (excluding bits already consumed). */
76
+ remainingBits(): number;
77
+ /** Refs remaining (excluding refs already consumed). */
78
+ remainingRefs(): number;
79
+ /** Read an unsigned big-endian integer of `bits` bits. */
80
+ loadUint(bits: number): bigint;
81
+ /** Read a signed big-endian integer of `bits` bits. */
82
+ loadInt(bits: number): bigint;
83
+ /** Read a single bit (0/1). */
84
+ loadBit(): 0 | 1;
85
+ /** Read `bytes` bytes (errors if not byte-aligned at the cursor). */
86
+ loadBuffer(bytes: number): Uint8Array;
87
+ /** Pop the next ref (errors if no refs remain). */
88
+ loadRef(): Cell;
89
+ /** Read remaining bits as a left-aligned bit buffer + bit length. */
90
+ loadRemainingBits(): {
91
+ bits: Uint8Array;
92
+ bitLen: number;
93
+ };
94
+ }
95
+ /** Open a read-side slice over `cell`. */
96
+ export declare function beginParse(cell: Cell): CellSlice;
97
+ /**
98
+ * TEP-74 `VarUInteger 16` decoder: 4-bit length prefix `n` (0..15) followed by
99
+ * `n*8` bits of big-endian unsigned integer. n=0 → value=0. Returns `bigint`.
100
+ *
101
+ * @source github.com/ton-blockchain/TIPs/issues/74 (TEP-74 Fungible Tokens),
102
+ * `Coins` / `VarUInteger 16` definition. Cross-checked against TL-B
103
+ * reference (https://docs.ton.org/develop/data-formats/tl-b-types).
104
+ */
105
+ export declare function readVarUInteger16(slice: CellSlice): bigint;
106
+ /**
107
+ * TL-B `MsgAddress` decoder narrowed to the `addr_std` shape — the only form
108
+ * that matters for end-user senders in jetton transfer/notification flows.
109
+ * Returns `null` for `addr_none`; throws for `addr_extern`/`addr_var`/anycast.
110
+ *
111
+ * addr_none$00 = MsgAddressExt;
112
+ * addr_extern$01 = MsgAddressExt;
113
+ * anycast_info$_ depth:(#<= 30) rewrite_pfx:(bits depth) = Anycast;
114
+ * addr_std$10 anycast:(Maybe Anycast)
115
+ * workchain_id:int8 address:bits256 = MsgAddressInt;
116
+ * addr_var$110 anycast:(Maybe Anycast)
117
+ * addr_len:(## 9) workchain_id:int32 address:(bits addr_len) = MsgAddressInt;
118
+ *
119
+ * @source TL-B reference https://docs.ton.org/develop/data-formats/tl-b-types
120
+ * (`MsgAddress`); cross-checked at impl time 2026-04-29 against TonConsole
121
+ * Cookbook jetton-transfer notes.
122
+ */
123
+ export declare function readMsgAddress(slice: CellSlice): {
124
+ workchain: number;
125
+ hex: string;
126
+ } | null;
127
+ /**
128
+ * Parse a single-root BoC (magic `0xb5ee9c72`) hex string into a `Cell`. Only
129
+ * the variant we need for the wallet/jetton code BoCs we vendor: no idx, no
130
+ * cache_bits, optional crc32c trailer (validated when present).
131
+ *
132
+ * @source github.com/ton-org/ton-core/src/boc/cell/serialization.ts —
133
+ * `parseBoc` + `deserializeBoc` for magic `0xb5ee9c72`. CRC32-C validation
134
+ * intentionally skipped (the wallet sources we vendor are constants — any
135
+ * tampering would surface immediately as a derivation mismatch in tests).
136
+ */
137
+ export declare function deserializeBoC(hex: string): Cell;
138
+ /**
139
+ * Build the StateInit cell for a wallet contract:
140
+ * `_ split_depth:(Maybe (## 5)) special:(Maybe TickTock) code:(Maybe ^Cell)
141
+ * data:(Maybe ^Cell) library:(HashmapE 256 SimpleLib) = StateInit;`
142
+ *
143
+ * The per-version data-cell layout differs (v3R2 vs v4R2 vs v5R1), so the
144
+ * caller supplies a `dataCellBuilder` lambda — keeping this function
145
+ * version-agnostic.
146
+ *
147
+ * @source github.com/ton-org/ton-core/src/types/StateInit.ts — `storeStateInit`.
148
+ */
149
+ export declare function buildStateInit(opts: {
150
+ codeBoCHex: string;
151
+ subwalletId: number;
152
+ publicKeyHex: string;
153
+ workchain: number;
154
+ dataCellBuilder: (input: {
155
+ subwalletId: number;
156
+ publicKeyHex: string;
157
+ }) => Cell;
158
+ }): Cell;
159
+ /**
160
+ * Compute the on-chain account-id for a TON wallet contract. The hex form is
161
+ * the 32-byte representation hash of the `StateInit` cell; pair with
162
+ * `serializeAddressUserFriendly` at API boundaries.
163
+ *
164
+ * @source github.com/ton-org/ton-core/src/address/contractAddress.ts.
165
+ */
166
+ export declare function computeWalletAddress(opts: {
167
+ codeBoCHex: string;
168
+ subwalletId: number;
169
+ publicKeyHex: string;
170
+ workchain: number;
171
+ dataCellBuilder: (input: {
172
+ subwalletId: number;
173
+ publicKeyHex: string;
174
+ }) => Cell;
175
+ }): {
176
+ workchain: number;
177
+ hex: string;
178
+ };
179
+ //# sourceMappingURL=ton-cell.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ton-cell.d.ts","sourceRoot":"","sources":["../../../src/verify/chains/ton-cell.ts"],"names":[],"mappings":"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"}