@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.
- package/LICENSE +201 -0
- package/README.md +391 -0
- package/dist/client.d.ts +640 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +1730 -0
- package/dist/client.js.map +1 -0
- package/dist/codec-adapter.d.ts +33 -0
- package/dist/codec-adapter.d.ts.map +1 -0
- package/dist/codec-adapter.js +419 -0
- package/dist/codec-adapter.js.map +1 -0
- package/dist/codec.d.ts +137 -0
- package/dist/codec.d.ts.map +1 -0
- package/dist/codec.js +229 -0
- package/dist/codec.js.map +1 -0
- package/dist/crypto.d.ts +78 -0
- package/dist/crypto.d.ts.map +1 -0
- package/dist/crypto.js +145 -0
- package/dist/crypto.js.map +1 -0
- package/dist/errors.d.ts +122 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +397 -0
- package/dist/errors.js.map +1 -0
- package/dist/governance-query.d.ts +47 -0
- package/dist/governance-query.d.ts.map +1 -0
- package/dist/governance-query.js +525 -0
- package/dist/governance-query.js.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +22 -0
- package/dist/index.js.map +1 -0
- package/dist/testing.d.ts +25 -0
- package/dist/testing.d.ts.map +1 -0
- package/dist/testing.js +22 -0
- package/dist/testing.js.map +1 -0
- package/dist/trigger-history.d.ts +9 -0
- package/dist/trigger-history.d.ts.map +1 -0
- package/dist/trigger-history.js +442 -0
- package/dist/trigger-history.js.map +1 -0
- package/dist/triggers.d.ts +15 -0
- package/dist/triggers.d.ts.map +1 -0
- package/dist/triggers.js +399 -0
- package/dist/triggers.js.map +1 -0
- package/dist/tx-result.d.ts +53 -0
- package/dist/tx-result.d.ts.map +1 -0
- package/dist/tx-result.js +58 -0
- package/dist/tx-result.js.map +1 -0
- package/dist/types.d.ts +2085 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +121 -0
- package/dist/types.js.map +1 -0
- package/dist/wasm/proof_trading_sdk_wasm.d.ts +98 -0
- package/dist/wasm/proof_trading_sdk_wasm.js +698 -0
- package/dist/wasm/proof_trading_sdk_wasm_bg.wasm +0 -0
- package/dist/wasm/proof_trading_sdk_wasm_bg.wasm.d.ts +19 -0
- package/dist/wasm-loader.d.ts +42 -0
- package/dist/wasm-loader.d.ts.map +1 -0
- package/dist/wasm-loader.js +95 -0
- package/dist/wasm-loader.js.map +1 -0
- package/package.json +72 -0
package/dist/codec.d.ts
ADDED
|
@@ -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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"}
|
package/dist/crypto.d.ts
ADDED
|
@@ -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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"}
|