@proof-labs/trading-sdk 4.0.0

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 (59) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +391 -0
  3. package/dist/client.d.ts +640 -0
  4. package/dist/client.d.ts.map +1 -0
  5. package/dist/client.js +1730 -0
  6. package/dist/client.js.map +1 -0
  7. package/dist/codec-adapter.d.ts +33 -0
  8. package/dist/codec-adapter.d.ts.map +1 -0
  9. package/dist/codec-adapter.js +419 -0
  10. package/dist/codec-adapter.js.map +1 -0
  11. package/dist/codec.d.ts +137 -0
  12. package/dist/codec.d.ts.map +1 -0
  13. package/dist/codec.js +229 -0
  14. package/dist/codec.js.map +1 -0
  15. package/dist/crypto.d.ts +78 -0
  16. package/dist/crypto.d.ts.map +1 -0
  17. package/dist/crypto.js +145 -0
  18. package/dist/crypto.js.map +1 -0
  19. package/dist/errors.d.ts +122 -0
  20. package/dist/errors.d.ts.map +1 -0
  21. package/dist/errors.js +397 -0
  22. package/dist/errors.js.map +1 -0
  23. package/dist/governance-query.d.ts +47 -0
  24. package/dist/governance-query.d.ts.map +1 -0
  25. package/dist/governance-query.js +525 -0
  26. package/dist/governance-query.js.map +1 -0
  27. package/dist/index.d.ts +11 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +22 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/testing.d.ts +25 -0
  32. package/dist/testing.d.ts.map +1 -0
  33. package/dist/testing.js +22 -0
  34. package/dist/testing.js.map +1 -0
  35. package/dist/trigger-history.d.ts +9 -0
  36. package/dist/trigger-history.d.ts.map +1 -0
  37. package/dist/trigger-history.js +442 -0
  38. package/dist/trigger-history.js.map +1 -0
  39. package/dist/triggers.d.ts +15 -0
  40. package/dist/triggers.d.ts.map +1 -0
  41. package/dist/triggers.js +399 -0
  42. package/dist/triggers.js.map +1 -0
  43. package/dist/tx-result.d.ts +53 -0
  44. package/dist/tx-result.d.ts.map +1 -0
  45. package/dist/tx-result.js +58 -0
  46. package/dist/tx-result.js.map +1 -0
  47. package/dist/types.d.ts +2085 -0
  48. package/dist/types.d.ts.map +1 -0
  49. package/dist/types.js +121 -0
  50. package/dist/types.js.map +1 -0
  51. package/dist/wasm/proof_trading_sdk_wasm.d.ts +98 -0
  52. package/dist/wasm/proof_trading_sdk_wasm.js +698 -0
  53. package/dist/wasm/proof_trading_sdk_wasm_bg.wasm +0 -0
  54. package/dist/wasm/proof_trading_sdk_wasm_bg.wasm.d.ts +19 -0
  55. package/dist/wasm-loader.d.ts +42 -0
  56. package/dist/wasm-loader.d.ts.map +1 -0
  57. package/dist/wasm-loader.js +95 -0
  58. package/dist/wasm-loader.js.map +1 -0
  59. package/package.json +72 -0
@@ -0,0 +1,137 @@
1
+ import { type Action, type ActionTypeValue, type AdminAction } from "./types.js";
2
+ /**
3
+ * The action payload codec and signing now run through the WASM build of the
4
+ * Rust core (`crates/proof-trading-sdk-wasm`), so the bytes are identical to
5
+ * the exchange engine **by construction** — see
6
+ * `docs/adr/0001-wasm-core-vs-parallel-types.md`. The old hand-written
7
+ * positional codec (~770 lines) is gone; this module is a thin, name/enum
8
+ * adapter (`codec-adapter.ts`) plus the outer-envelope framing.
9
+ *
10
+ * **Initialization:** WASM instantiation is asynchronous, so call
11
+ * `await ready()` (re-exported from the SDK entrypoint, or via
12
+ * `ExchangeClient.ready()`) once before any encode/decode/sign call below.
13
+ * After it resolves these functions run synchronously; `getWasm()` throws a
14
+ * clear error if `ready()` has not completed.
15
+ */
16
+ /**
17
+ * Envelope version byte — the first element of the wire array
18
+ * `[version, actionType, seq, payload, pubkey, signature]`. The exchange
19
+ * engine accepts only version `2`.
20
+ *
21
+ * Distinct from the signing domain prefix `"ProofExchange-v3"` (see
22
+ * `crypto.ts` and CLAUDE.md "Two distinct version numbers"): the envelope
23
+ * version is `2`, the signing layout is v3.
24
+ */
25
+ export declare const ENVELOPE_VERSION = 2;
26
+ /**
27
+ * Encode just the payload bytes for an action (no signed envelope). The bytes
28
+ * match `rmp-serde` — and therefore the engine — byte-for-byte.
29
+ */
30
+ export declare function encodePayloadBytes(action: Action): Uint8Array;
31
+ /**
32
+ * Encode a signed wire envelope from a pre-computed pubkey + signature.
33
+ * Most callers should use `signAndEncode` instead; this exists for paths that
34
+ * already hold raw signature bytes.
35
+ */
36
+ export declare function encodeSignedTx(action: Action, seq: bigint, pubkey: Uint8Array, signature: Uint8Array): Uint8Array;
37
+ /**
38
+ * Sign an action and encode it as a V2 wire envelope, binding the signature to
39
+ * `chainId` (audit B4). Production signers must pass
40
+ * `chainIdFromString(cometbftChainId)`; only unit tests should pass
41
+ * `UNBOUND_CHAIN_ID`. `ExchangeClient` resolves and caches this automatically —
42
+ * call this directly only when bypassing the client.
43
+ */
44
+ export declare function signAndEncode(chainId: Uint8Array, action: Action, seq: bigint, privateKey: Uint8Array): Uint8Array;
45
+ /**
46
+ * Sign and encode a raw pre-encoded payload into a V2 signed envelope. Lower
47
+ * level than `signAndEncode` — callers supply already-encoded payload bytes and
48
+ * the action-type byte directly. Useful for cross-language conformance testing.
49
+ */
50
+ export declare function signEnvelopeFromPayload(chainId: Uint8Array, actionType: number, seq: bigint, payloadBytes: Uint8Array, privateKey: Uint8Array): Uint8Array;
51
+ /** Immutable proposal context committed by the §2.4 content hash. Field for
52
+ * field the hash preimage — see `ApproveAdminAction`, which carries the same
53
+ * context plus the hash itself. */
54
+ export interface AdminProposalContext {
55
+ /** 32-byte chain-id binding (`chainIdFromString(cometbftChainId)`). */
56
+ chainId: Uint8Array;
57
+ proposalId: bigint;
58
+ registryVersion: bigint;
59
+ threshold: number;
60
+ /** Address that created the proposal (20 bytes). */
61
+ proposer: Uint8Array;
62
+ createdHeight: bigint;
63
+ createdMs: bigint;
64
+ expiryMs: bigint;
65
+ action: AdminAction;
66
+ }
67
+ /**
68
+ * Recompute the engine's domain-separated admin-proposal content hash
69
+ * (32 bytes) in the authoritative Rust core (§2.4,
70
+ * `PROOF_ADMIN_PROPOSAL_V1` preimage).
71
+ *
72
+ * An approving signer should recompute this from the full proposal context
73
+ * and compare it to the `content_hash` a server hands them — **never sign a
74
+ * hash they did not recompute**. Byte-equality with the engine is pinned by
75
+ * the core's golden-vector test.
76
+ */
77
+ export declare function adminProposalContentHash(ctx: AdminProposalContext): Uint8Array;
78
+ /** Peek at the action_type byte without a full decode.
79
+ *
80
+ * Returns `null` both for structurally unreadable bytes AND for an
81
+ * action-type slot this SDK build does not know (an unassigned byte, a
82
+ * newer engine's wire type under an older SDK, or a non-numeric msgpack
83
+ * value), matching its declared return type — never a raw slot value cast
84
+ * through unvalidated. Callers that need the raw byte of an unknown envelope
85
+ * should decode the envelope themselves. */
86
+ export declare function peekActionType(bytes: Uint8Array): ActionTypeValue | null;
87
+ /** Decode wire bytes into an action + sequence number + auth fields. */
88
+ export declare function decodeTx(bytes: Uint8Array): {
89
+ action: Action;
90
+ seq: bigint;
91
+ version: number;
92
+ pubkey: Uint8Array;
93
+ signature: Uint8Array;
94
+ };
95
+ /**
96
+ * Decoded form of a v3 **signing preimage** — the exact bytes
97
+ * `signingMessage()` produces and an external signer signs. Not to be
98
+ * confused with the wire envelope `decodeTx()` decodes (which additionally
99
+ * carries the pubkey and signature).
100
+ */
101
+ export interface DecodedSigningMessage {
102
+ /** The 32-byte chain id the signature will bind to (cross-chain replay guard). */
103
+ chainId: Uint8Array;
104
+ /** Wire action-type byte. */
105
+ actionType: number;
106
+ /** SDK name for `actionType`, or null when this SDK build doesn't know the byte. */
107
+ actionName: string | null;
108
+ /** Per-signer sequence field (u64; big-endian on the wire). */
109
+ seq: bigint;
110
+ /** Raw payload bytes (a MessagePack positional array). */
111
+ payloadBytes: Uint8Array;
112
+ /** The decoded action, or null when the payload could not be decoded. */
113
+ action: Action | null;
114
+ /** Present exactly when `action` is null — why the payload didn't decode. */
115
+ decodeError: string | null;
116
+ }
117
+ /**
118
+ * Decode a v3 signing preimage (`DOMAIN_PREFIX(16) || chain_id(32) ||
119
+ * action_type(1) || seq_be(8) || payload`) back into its parts, so a
120
+ * signer-side tool can show a human WHAT they are about to sign on a trust
121
+ * base independent of whoever built the bytes — the external-signer
122
+ * counterpart of `decodeTx()`.
123
+ *
124
+ * Throws when the input is structurally not a Proof v3 signing preimage
125
+ * (too short, or wrong domain prefix) — a signer tool should treat that as
126
+ * "refuse loudly", not display garbage. An unknown action-type byte or an
127
+ * undecodable payload is NOT structural: the envelope fields still parse
128
+ * and are returned, with `action: null` and `decodeError` explaining why —
129
+ * newer wire actions than this SDK build must degrade to "cannot decode,
130
+ * here are the raw bytes", never to a false structural rejection.
131
+ *
132
+ * The payload is decoded — and re-encoded for the canonical-form check —
133
+ * through the WASM core, so the accepted preimage bytes are exactly those
134
+ * `signAndEncode` produces.
135
+ */
136
+ export declare function decodeSigningMessage(msg: Uint8Array): DecodedSigningMessage;
137
+ //# sourceMappingURL=codec.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,MAAM,EAEX,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAWlC;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAG7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,UAAU,GACpB,UAAU,CAKZ;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,UAAU,GACrB,UAAU,CAKZ;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,UAAU,EACxB,UAAU,EAAE,UAAU,GACrB,UAAU,CAQZ;AAED;;oCAEoC;AACpC,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,OAAO,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,UAAU,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,oBAAoB,GACxB,UAAU,CAYZ;AAYD;;;;;;;6CAO6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,GAAG,IAAI,CAcxE;AAaD,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,UAAU,CAAC;CACvB,CAsBA;AAUD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,OAAO,EAAE,UAAU,CAAC;IACpB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,YAAY,EAAE,UAAU,CAAC;IACzB,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,qBAAqB,CAmE3E"}
package/dist/codec.js ADDED
@@ -0,0 +1,229 @@
1
+ import { Decoder } from "@msgpack/msgpack";
2
+ import { ActionType, } from "./types.js";
3
+ import { getWasm } from "./wasm-loader.js";
4
+ import { adminActionToWasm, toWasmFields, fromWasmFields, } from "./codec-adapter.js";
5
+ import { DOMAIN_PREFIX } from "./crypto.js";
6
+ /**
7
+ * The action payload codec and signing now run through the WASM build of the
8
+ * Rust core (`crates/proof-trading-sdk-wasm`), so the bytes are identical to
9
+ * the exchange engine **by construction** — see
10
+ * `docs/adr/0001-wasm-core-vs-parallel-types.md`. The old hand-written
11
+ * positional codec (~770 lines) is gone; this module is a thin, name/enum
12
+ * adapter (`codec-adapter.ts`) plus the outer-envelope framing.
13
+ *
14
+ * **Initialization:** WASM instantiation is asynchronous, so call
15
+ * `await ready()` (re-exported from the SDK entrypoint, or via
16
+ * `ExchangeClient.ready()`) once before any encode/decode/sign call below.
17
+ * After it resolves these functions run synchronously; `getWasm()` throws a
18
+ * clear error if `ready()` has not completed.
19
+ */
20
+ /**
21
+ * Envelope version byte — the first element of the wire array
22
+ * `[version, actionType, seq, payload, pubkey, signature]`. The exchange
23
+ * engine accepts only version `2`.
24
+ *
25
+ * Distinct from the signing domain prefix `"ProofExchange-v3"` (see
26
+ * `crypto.ts` and CLAUDE.md "Two distinct version numbers"): the envelope
27
+ * version is `2`, the signing layout is v3.
28
+ */
29
+ export const ENVELOPE_VERSION = 2;
30
+ // Only the OUTER signed-envelope array is still read with @msgpack — that is a
31
+ // trivial positional read (version/type/seq/payload-bytes/pubkey/sig), not the
32
+ // action codec, so it needs no WASM. `useBigInt64` keeps large seq values exact.
33
+ const decoder = new Decoder({ useBigInt64: true });
34
+ // ---------------------------------------------------------------------------
35
+ // Encoding + signing (via WASM)
36
+ // ---------------------------------------------------------------------------
37
+ /**
38
+ * Encode just the payload bytes for an action (no signed envelope). The bytes
39
+ * match `rmp-serde` — and therefore the engine — byte-for-byte.
40
+ */
41
+ export function encodePayloadBytes(action) {
42
+ const { actionType, fields } = toWasmFields(action);
43
+ return getWasm().encode_payload(actionType, fields);
44
+ }
45
+ /**
46
+ * Encode a signed wire envelope from a pre-computed pubkey + signature.
47
+ * Most callers should use `signAndEncode` instead; this exists for paths that
48
+ * already hold raw signature bytes.
49
+ */
50
+ export function encodeSignedTx(action, seq, pubkey, signature) {
51
+ const { actionType, fields } = toWasmFields(action);
52
+ const wasm = getWasm();
53
+ const payload = wasm.encode_payload(actionType, fields);
54
+ return wasm.encode_signed_tx(actionType, payload, seq, pubkey, signature);
55
+ }
56
+ /**
57
+ * Sign an action and encode it as a V2 wire envelope, binding the signature to
58
+ * `chainId` (audit B4). Production signers must pass
59
+ * `chainIdFromString(cometbftChainId)`; only unit tests should pass
60
+ * `UNBOUND_CHAIN_ID`. `ExchangeClient` resolves and caches this automatically —
61
+ * call this directly only when bypassing the client.
62
+ */
63
+ export function signAndEncode(chainId, action, seq, privateKey) {
64
+ const { actionType, fields } = toWasmFields(action);
65
+ const wasm = getWasm();
66
+ const payload = wasm.encode_payload(actionType, fields);
67
+ return wasm.sign_and_encode(chainId, actionType, payload, seq, privateKey);
68
+ }
69
+ /**
70
+ * Sign and encode a raw pre-encoded payload into a V2 signed envelope. Lower
71
+ * level than `signAndEncode` — callers supply already-encoded payload bytes and
72
+ * the action-type byte directly. Useful for cross-language conformance testing.
73
+ */
74
+ export function signEnvelopeFromPayload(chainId, actionType, seq, payloadBytes, privateKey) {
75
+ return getWasm().sign_and_encode(chainId, actionType, payloadBytes, seq, privateKey);
76
+ }
77
+ /**
78
+ * Recompute the engine's domain-separated admin-proposal content hash
79
+ * (32 bytes) in the authoritative Rust core (§2.4,
80
+ * `PROOF_ADMIN_PROPOSAL_V1` preimage).
81
+ *
82
+ * An approving signer should recompute this from the full proposal context
83
+ * and compare it to the `content_hash` a server hands them — **never sign a
84
+ * hash they did not recompute**. Byte-equality with the engine is pinned by
85
+ * the core's golden-vector test.
86
+ */
87
+ export function adminProposalContentHash(ctx) {
88
+ return getWasm().admin_proposal_content_hash(ctx.chainId, ctx.proposalId, ctx.registryVersion, ctx.threshold, ctx.proposer, ctx.createdHeight, ctx.createdMs, ctx.expiryMs, adminActionToWasm(ctx.action));
89
+ }
90
+ // ---------------------------------------------------------------------------
91
+ // Decoding
92
+ // ---------------------------------------------------------------------------
93
+ /** Every wire action-type byte this SDK build knows — the validation set
94
+ * behind `peekActionType`'s return type. */
95
+ const KNOWN_ACTION_TYPES = new Set(Object.values(ActionType));
96
+ /** Peek at the action_type byte without a full decode.
97
+ *
98
+ * Returns `null` both for structurally unreadable bytes AND for an
99
+ * action-type slot this SDK build does not know (an unassigned byte, a
100
+ * newer engine's wire type under an older SDK, or a non-numeric msgpack
101
+ * value), matching its declared return type — never a raw slot value cast
102
+ * through unvalidated. Callers that need the raw byte of an unknown envelope
103
+ * should decode the envelope themselves. */
104
+ export function peekActionType(bytes) {
105
+ try {
106
+ const envelope = decoder.decode(bytes);
107
+ const raw = envelope[1];
108
+ const value = typeof raw === "number"
109
+ ? raw
110
+ : typeof raw === "bigint"
111
+ ? Number(raw)
112
+ : NaN;
113
+ return KNOWN_ACTION_TYPES.has(value) ? value : null;
114
+ }
115
+ catch {
116
+ return null;
117
+ }
118
+ }
119
+ /**
120
+ * Coerce a decoded msgpack int (returned as `number` for a fixint or `bigint`
121
+ * for a uint64) into a single bigint, so `seq` is one stable type regardless of
122
+ * how the encoder chose to represent it on the wire.
123
+ */
124
+ function toBigInt(v) {
125
+ if (typeof v === "bigint")
126
+ return v;
127
+ if (typeof v === "number")
128
+ return BigInt(v);
129
+ throw new Error(`expected number/bigint, got ${typeof v}: ${v}`);
130
+ }
131
+ /** Decode wire bytes into an action + sequence number + auth fields. */
132
+ export function decodeTx(bytes) {
133
+ const envelope = decoder.decode(bytes);
134
+ const version = envelope[0];
135
+ if (version !== ENVELOPE_VERSION) {
136
+ throw new Error(`unsupported version: ${version}`);
137
+ }
138
+ const actionType = envelope[1];
139
+ const seq = toBigInt(envelope[2]);
140
+ const payloadBytes = envelope[3];
141
+ // The action payload is decoded by the WASM core (authoritative), then mapped
142
+ // back to the TS `Action` shape by the adapter.
143
+ const action = fromWasmFields(actionType, getWasm().decode_payload(actionType, payloadBytes));
144
+ return {
145
+ action,
146
+ seq,
147
+ version,
148
+ pubkey: envelope[4],
149
+ signature: envelope[5],
150
+ };
151
+ }
152
+ // ---------------------------------------------------------------------------
153
+ // Signing-preimage decode (signer-side review)
154
+ // ---------------------------------------------------------------------------
155
+ const ACTION_TYPE_NAMES = new Map(Object.entries(ActionType).map(([name, byte]) => [byte, name]));
156
+ /**
157
+ * Decode a v3 signing preimage (`DOMAIN_PREFIX(16) || chain_id(32) ||
158
+ * action_type(1) || seq_be(8) || payload`) back into its parts, so a
159
+ * signer-side tool can show a human WHAT they are about to sign on a trust
160
+ * base independent of whoever built the bytes — the external-signer
161
+ * counterpart of `decodeTx()`.
162
+ *
163
+ * Throws when the input is structurally not a Proof v3 signing preimage
164
+ * (too short, or wrong domain prefix) — a signer tool should treat that as
165
+ * "refuse loudly", not display garbage. An unknown action-type byte or an
166
+ * undecodable payload is NOT structural: the envelope fields still parse
167
+ * and are returned, with `action: null` and `decodeError` explaining why —
168
+ * newer wire actions than this SDK build must degrade to "cannot decode,
169
+ * here are the raw bytes", never to a false structural rejection.
170
+ *
171
+ * The payload is decoded — and re-encoded for the canonical-form check —
172
+ * through the WASM core, so the accepted preimage bytes are exactly those
173
+ * `signAndEncode` produces.
174
+ */
175
+ export function decodeSigningMessage(msg) {
176
+ const headerLen = DOMAIN_PREFIX.length + 32 + 1 + 8;
177
+ if (msg.length < headerLen) {
178
+ throw new Error(`not a Proof v3 signing message: ${msg.length} bytes is shorter than ` +
179
+ `the ${headerLen}-byte fixed header`);
180
+ }
181
+ for (let i = 0; i < DOMAIN_PREFIX.length; i++) {
182
+ if (msg[i] !== DOMAIN_PREFIX[i]) {
183
+ throw new Error('not a Proof v3 signing message: missing the "ProofExchange-v3" ' +
184
+ "domain prefix");
185
+ }
186
+ }
187
+ let offset = DOMAIN_PREFIX.length;
188
+ const chainId = msg.slice(offset, offset + 32);
189
+ offset += 32;
190
+ const actionType = msg[offset++];
191
+ const seq = new DataView(msg.buffer, msg.byteOffset + offset, 8).getBigUint64(0, false);
192
+ offset += 8;
193
+ const payloadBytes = msg.slice(offset);
194
+ const actionName = ACTION_TYPE_NAMES.get(actionType) ?? null;
195
+ let action = null;
196
+ let decodeError = null;
197
+ if (actionName === null) {
198
+ decodeError = `unknown action type 0x${actionType.toString(16).padStart(2, "0")} — not in this SDK build`;
199
+ }
200
+ else {
201
+ try {
202
+ // Decode via the WASM core (authoritative), then confirm the bytes are
203
+ // the canonical representation by re-encoding through the same core and
204
+ // comparing — a non-canonical payload is not something we can safely
205
+ // display, so it degrades to `decodeError`.
206
+ const decodedAction = fromWasmFields(actionType, getWasm().decode_payload(actionType, payloadBytes));
207
+ const canonicalPayloadBytes = encodePayloadBytes(decodedAction);
208
+ const isCanonical = canonicalPayloadBytes.length === payloadBytes.length &&
209
+ canonicalPayloadBytes.every((byte, i) => byte === payloadBytes[i]);
210
+ if (!isCanonical) {
211
+ throw new Error("payload is not the canonical representation this SDK can safely display");
212
+ }
213
+ action = decodedAction;
214
+ }
215
+ catch (e) {
216
+ decodeError = e instanceof Error ? e.message : String(e);
217
+ }
218
+ }
219
+ return {
220
+ chainId,
221
+ actionType,
222
+ actionName,
223
+ seq,
224
+ payloadBytes,
225
+ action,
226
+ decodeError,
227
+ };
228
+ }
229
+ //# sourceMappingURL=codec.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Domain separator matching Rust: `b"ProofExchange-v3"` (16 bytes).
3
+ * Bumped from v2 on 2026-04-23 (audit finding B4) when the envelope
4
+ * gained a 32-byte `chain_id` binding. A v2-signed tx submitted to a
5
+ * v3 engine verifies against different message bytes and fails —
6
+ * protects against cross-chain and post-wipe replay.
7
+ */
8
+ /**
9
+ * The 16-byte signing domain prefix every v3 signing message starts with.
10
+ * Exported so signer-side tools can recognize (and decode) a Proof signing
11
+ * preimage before putting it in front of a human — see
12
+ * `decodeSigningMessage()` in codec.ts. Changing this value is a MAJOR wire
13
+ * break (see CLAUDE.md "Versioning"); it is distinct from the envelope
14
+ * version byte (`ENVELOPE_VERSION` = 2).
15
+ */
16
+ export declare const DOMAIN_PREFIX: Uint8Array<ArrayBuffer>;
17
+ /**
18
+ * 32-byte zero chain_id — unbound chain. Production signers MUST
19
+ * use a real chain_id (typically `keccak256(cometbft_chain_id_string)`)
20
+ * or their signatures are trivially replayable on any other
21
+ * zero-chain_id deployment.
22
+ *
23
+ * NOTE: Treat this as read-only. It is a single shared instance and
24
+ * cannot be truly frozen — `Object.freeze` throws on a non-empty typed
25
+ * array, and freezing the backing `ArrayBuffer` does not stop element
26
+ * writes through the view. Do NOT mutate it; copy it (`.slice()`) first
27
+ * if you need a writable 32-byte buffer. `ExchangeClient` defensively
28
+ * copies before caching so an external mutation cannot corrupt its
29
+ * signing chain_id.
30
+ */
31
+ export declare const UNBOUND_CHAIN_ID: Uint8Array<ArrayBuffer>;
32
+ /**
33
+ * Hash a CometBFT chain_id string into the 32-byte binding used by
34
+ * the v3 signing envelope. Matches `chain_id_from_string` in Rust
35
+ * `crypto.rs` byte-for-byte.
36
+ */
37
+ export declare function chainIdFromString(chainId: string): Uint8Array;
38
+ /** Generate a new Ed25519 keypair. */
39
+ export declare function generateKeypair(): {
40
+ privateKey: Uint8Array;
41
+ publicKey: Uint8Array;
42
+ };
43
+ /** Get public key from private key. */
44
+ export declare function getPublicKey(privateKey: Uint8Array): Uint8Array;
45
+ /**
46
+ * Derive 20-byte owner address from 32-byte Ed25519 public key.
47
+ * keccak256(pubkey)[12..32] — matches Rust `pubkey_to_owner`.
48
+ */
49
+ export declare function pubkeyToOwner(pubkey: Uint8Array): Uint8Array;
50
+ /** Convert a 20-byte address to hex string. */
51
+ export declare function ownerToHex(owner: Uint8Array): string;
52
+ /**
53
+ * Parse a hex string (with or without a `0x` prefix) into bytes.
54
+ *
55
+ * Throws on malformed input — an odd number of digits or any
56
+ * non-hexadecimal character — rather than silently substituting zero
57
+ * bytes (`parseInt` on bad input yields `NaN`, which coerces to `0` in a
58
+ * `Uint8Array`). Silent corruption on a key/address/signature field is a
59
+ * security hazard, so validate up front.
60
+ */
61
+ export declare function hexToBytes(hex: string): Uint8Array;
62
+ /** Convert bytes to hex string. */
63
+ export declare function bytesToHex(bytes: Uint8Array): string;
64
+ /**
65
+ * Construct the deterministic signing message for a transaction.
66
+ *
67
+ * V3 layout: `DOMAIN_PREFIX(16) || chain_id(32) || action_type(1) || seq_be(8) || payload`
68
+ *
69
+ * Matches Rust `signing_message()` in `crypto.rs`. The `chainId`
70
+ * argument must be 32 bytes — usually `chainIdFromString(cometbft_chain_id)`
71
+ * or `UNBOUND_CHAIN_ID` for unit-test-only use.
72
+ */
73
+ export declare function signingMessage(chainId: Uint8Array, actionType: number, seq: bigint, payload: Uint8Array): Uint8Array;
74
+ /** Sign a message with Ed25519. Returns 64-byte signature. */
75
+ export declare function sign(privateKey: Uint8Array, message: Uint8Array): Uint8Array;
76
+ /** Verify an Ed25519 signature. */
77
+ export declare function verify(publicKey: Uint8Array, signature: Uint8Array, message: Uint8Array): boolean;
78
+ //# sourceMappingURL=crypto.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAiCA;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,yBAA+C,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,yBAAqB,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAE7D;AAED,sCAAsC;AACtC,wBAAgB,eAAe,IAAI;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;CACvB,CAUA;AAED,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAG5D;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAalD;AAED,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,GAClB,UAAU,CAmBZ;AAED,8DAA8D;AAC9D,wBAAgB,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,CAE5E;AAED,mCAAmC;AACnC,wBAAgB,MAAM,CACpB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,GAClB,OAAO,CAET"}
package/dist/crypto.js ADDED
@@ -0,0 +1,145 @@
1
+ import * as ed25519 from "@noble/ed25519";
2
+ import { keccak_256 } from "@noble/hashes/sha3.js";
3
+ import { sha512 } from "@noble/hashes/sha2.js";
4
+ const nobleHashes = Reflect.get(ed25519, "hashes");
5
+ if (nobleHashes) {
6
+ nobleHashes.sha512 = sha512;
7
+ }
8
+ else {
9
+ const nobleEtc = ed25519.etc;
10
+ if (!("sha512Sync" in nobleEtc)) {
11
+ throw new Error("unsupported @noble/ed25519 hash API");
12
+ }
13
+ nobleEtc.sha512Sync = (...messages) => sha512(nobleEtc.concatBytes(...messages));
14
+ }
15
+ /**
16
+ * Domain separator matching Rust: `b"ProofExchange-v3"` (16 bytes).
17
+ * Bumped from v2 on 2026-04-23 (audit finding B4) when the envelope
18
+ * gained a 32-byte `chain_id` binding. A v2-signed tx submitted to a
19
+ * v3 engine verifies against different message bytes and fails —
20
+ * protects against cross-chain and post-wipe replay.
21
+ */
22
+ /**
23
+ * The 16-byte signing domain prefix every v3 signing message starts with.
24
+ * Exported so signer-side tools can recognize (and decode) a Proof signing
25
+ * preimage before putting it in front of a human — see
26
+ * `decodeSigningMessage()` in codec.ts. Changing this value is a MAJOR wire
27
+ * break (see CLAUDE.md "Versioning"); it is distinct from the envelope
28
+ * version byte (`ENVELOPE_VERSION` = 2).
29
+ */
30
+ export const DOMAIN_PREFIX = new TextEncoder().encode("ProofExchange-v3");
31
+ /**
32
+ * 32-byte zero chain_id — unbound chain. Production signers MUST
33
+ * use a real chain_id (typically `keccak256(cometbft_chain_id_string)`)
34
+ * or their signatures are trivially replayable on any other
35
+ * zero-chain_id deployment.
36
+ *
37
+ * NOTE: Treat this as read-only. It is a single shared instance and
38
+ * cannot be truly frozen — `Object.freeze` throws on a non-empty typed
39
+ * array, and freezing the backing `ArrayBuffer` does not stop element
40
+ * writes through the view. Do NOT mutate it; copy it (`.slice()`) first
41
+ * if you need a writable 32-byte buffer. `ExchangeClient` defensively
42
+ * copies before caching so an external mutation cannot corrupt its
43
+ * signing chain_id.
44
+ */
45
+ export const UNBOUND_CHAIN_ID = new Uint8Array(32);
46
+ /**
47
+ * Hash a CometBFT chain_id string into the 32-byte binding used by
48
+ * the v3 signing envelope. Matches `chain_id_from_string` in Rust
49
+ * `crypto.rs` byte-for-byte.
50
+ */
51
+ export function chainIdFromString(chainId) {
52
+ return keccak_256(new TextEncoder().encode(chainId));
53
+ }
54
+ /** Generate a new Ed25519 keypair. */
55
+ export function generateKeypair() {
56
+ const nobleUtils = ed25519.utils;
57
+ const randomSecretKey = Reflect.get(nobleUtils, "randomSecretKey") ?? nobleUtils.randomPrivateKey;
58
+ if (typeof randomSecretKey !== "function") {
59
+ throw new Error("unsupported @noble/ed25519 random-key API");
60
+ }
61
+ const privateKey = randomSecretKey.call(nobleUtils);
62
+ const publicKey = ed25519.getPublicKey(privateKey);
63
+ return { privateKey, publicKey };
64
+ }
65
+ /** Get public key from private key. */
66
+ export function getPublicKey(privateKey) {
67
+ return ed25519.getPublicKey(privateKey);
68
+ }
69
+ /**
70
+ * Derive 20-byte owner address from 32-byte Ed25519 public key.
71
+ * keccak256(pubkey)[12..32] — matches Rust `pubkey_to_owner`.
72
+ */
73
+ export function pubkeyToOwner(pubkey) {
74
+ const hash = keccak_256(pubkey);
75
+ return hash.slice(12, 32);
76
+ }
77
+ /** Convert a 20-byte address to hex string. */
78
+ export function ownerToHex(owner) {
79
+ return bytesToHex(owner);
80
+ }
81
+ /**
82
+ * Parse a hex string (with or without a `0x` prefix) into bytes.
83
+ *
84
+ * Throws on malformed input — an odd number of digits or any
85
+ * non-hexadecimal character — rather than silently substituting zero
86
+ * bytes (`parseInt` on bad input yields `NaN`, which coerces to `0` in a
87
+ * `Uint8Array`). Silent corruption on a key/address/signature field is a
88
+ * security hazard, so validate up front.
89
+ */
90
+ export function hexToBytes(hex) {
91
+ const h = hex.startsWith("0x") ? hex.slice(2) : hex;
92
+ if (h.length % 2 !== 0) {
93
+ throw new Error(`invalid hex: odd number of digits (${h.length})`);
94
+ }
95
+ if (h.length > 0 && !/^[0-9a-fA-F]+$/.test(h)) {
96
+ throw new Error("invalid hex: non-hexadecimal characters");
97
+ }
98
+ const bytes = new Uint8Array(h.length / 2);
99
+ for (let i = 0; i < bytes.length; i++) {
100
+ bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
101
+ }
102
+ return bytes;
103
+ }
104
+ /** Convert bytes to hex string. */
105
+ export function bytesToHex(bytes) {
106
+ return Array.from(bytes)
107
+ .map((b) => b.toString(16).padStart(2, "0"))
108
+ .join("");
109
+ }
110
+ /**
111
+ * Construct the deterministic signing message for a transaction.
112
+ *
113
+ * V3 layout: `DOMAIN_PREFIX(16) || chain_id(32) || action_type(1) || seq_be(8) || payload`
114
+ *
115
+ * Matches Rust `signing_message()` in `crypto.rs`. The `chainId`
116
+ * argument must be 32 bytes — usually `chainIdFromString(cometbft_chain_id)`
117
+ * or `UNBOUND_CHAIN_ID` for unit-test-only use.
118
+ */
119
+ export function signingMessage(chainId, actionType, seq, payload) {
120
+ if (chainId.length !== 32) {
121
+ throw new Error(`chain_id must be 32 bytes, got ${chainId.length}`);
122
+ }
123
+ const msg = new Uint8Array(DOMAIN_PREFIX.length + 32 + 1 + 8 + payload.length);
124
+ let offset = 0;
125
+ msg.set(DOMAIN_PREFIX, offset);
126
+ offset += DOMAIN_PREFIX.length;
127
+ msg.set(chainId, offset);
128
+ offset += 32;
129
+ msg[offset++] = actionType;
130
+ // seq as big-endian u64
131
+ const view = new DataView(msg.buffer, msg.byteOffset + offset, 8);
132
+ view.setBigUint64(0, seq, false); // false = big-endian
133
+ offset += 8;
134
+ msg.set(payload, offset);
135
+ return msg;
136
+ }
137
+ /** Sign a message with Ed25519. Returns 64-byte signature. */
138
+ export function sign(privateKey, message) {
139
+ return ed25519.sign(message, privateKey);
140
+ }
141
+ /** Verify an Ed25519 signature. */
142
+ export function verify(publicKey, signature, message) {
143
+ return ed25519.verify(signature, message, publicKey);
144
+ }
145
+ //# sourceMappingURL=crypto.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}