@xyo-network/xl1-protocol 5.6.1 → 5.7.0

package/dist/neutral/modules/protocol-lib/viewers/WindowedBlock.d.ts

@@ -4,6 +4,16 @@ import type { BlockViewerMethods } from './Block.js';
 type ExtendableBlockViewerMethods = Omit<BlockViewerMethods, 'blockByTransactionHash' | 'rate' | 'stepSizeRate' | 'timeDurationRate'>;
 /** Operations exposed by the Windowed Block Viewer contract. */
 export interface WindowedBlockViewerMethods extends ExtendableBlockViewerMethods {
+    /**
+     * Returns the blocks containing transactions with the supplied *data* hashes.
+     *
+     * A transaction's `_hash` covers its `$signatures`, so the same authorization can appear
+     * under more than one `_hash` — most importantly as the malleated (high-S) twin of a
+     * signature, which any observer can derive without the sender's key. `_dataHash` excludes
+     * the signatures and so identifies the transaction's *effect*. Inclusion checks that must
+     * not execute an effect twice have to key on this, not on `_hash`.
+     */
+    blocksByTransactionDataHashes(dataHashes: Hash[]): Promisable<HydratedBlockWithHashMeta[]>;
     /** Returns the result of the blocks by transaction hashes query. */
     blocksByTransactionHashes(hashes: Hash[]): Promisable<HydratedBlockWithHashMeta[]>;
 }
@@ -13,6 +23,13 @@ export declare const WindowedBlockViewerMoniker: "WindowedBlockViewer";
 export type WindowedBlockViewerMoniker = typeof WindowedBlockViewerMoniker;
 /** Viewer interface for reading WindowedBlock data. */
 export interface WindowedBlockViewer<TMoniker extends ProviderMoniker = WindowedBlockViewerMoniker> extends WindowedBlockViewerMethods, Provider<TMoniker> {
+    /**
+     * Returns the block containing a transaction with the supplied data hash, if any.
+     *
+     * See {@link WindowedBlockViewerMethods.blocksByTransactionDataHashes} for why inclusion
+     * checks key on `_dataHash` rather than `_hash`.
+     */
+    blockByTransactionDataHash(dataHash: Hash): Promisable<HydratedBlockWithHashMeta | null>;
     /** Returns the result of the block by transaction hash query. */
     blockByTransactionHash(hash: Hash): Promisable<HydratedBlockWithHashMeta | null>;
     /**

package/dist/neutral/modules/protocol-lib/viewers/WindowedBlock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WindowedBlock.d.ts","sourceRoot":"","sources":["../../../../../src/modules/protocol-lib/viewers/WindowedBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,KAAK,EACV,yBAAyB,EAAE,QAAQ,EAAE,eAAe,EACrD,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,KAAK,4BAA4B,GAAG,IAAI,CAAC,kBAAkB,EAAE,wBAAwB,GAAG,MAAM,GAAG,cAAc,GAAG,kBAAkB,CAAC,CAAA;AAErI,gEAAgE;AAChE,MAAM,WAAW,0BAA2B,SAAQ,4BAA4B;IAC9E,oEAAoE;IACpE,yBAAyB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,yBAAyB,EAAE,CAAC,CAAA;CACnF;AAED,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,EAAG,qBAA8B,CAAA;AACxE,iEAAiE;AACjE,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAA;AAE1E,uDAAuD;AACvD,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,eAAe,GAAG,0BAA0B,CAAE,SAAQ,0BAA0B,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACxJ,iEAAiE;IACjE,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAA;IAChF;;;;OAIG;IACH,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;CAC1B"}
+{"version":3,"file":"WindowedBlock.d.ts","sourceRoot":"","sources":["../../../../../src/modules/protocol-lib/viewers/WindowedBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,KAAK,EACV,yBAAyB,EAAE,QAAQ,EAAE,eAAe,EACrD,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,KAAK,4BAA4B,GAAG,IAAI,CAAC,kBAAkB,EAAE,wBAAwB,GAAG,MAAM,GAAG,cAAc,GAAG,kBAAkB,CAAC,CAAA;AAErI,gEAAgE;AAChE,MAAM,WAAW,0BAA2B,SAAQ,4BAA4B;IAC9E;;;;;;;;OAQG;IACH,6BAA6B,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,yBAAyB,EAAE,CAAC,CAAA;IAC1F,oEAAoE;IACpE,yBAAyB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,yBAAyB,EAAE,CAAC,CAAA;CACnF;AAED,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,EAAG,qBAA8B,CAAA;AACxE,iEAAiE;AACjE,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAA;AAE1E,uDAAuD;AACvD,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,eAAe,GAAG,0BAA0B,CAAE,SAAQ,0BAA0B,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACxJ;;;;;OAKG;IACH,0BAA0B,CAAC,QAAQ,EAAE,IAAI,GAAG,UAAU,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAA;IACxF,iEAAiE;IACjE,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAA;IAChF;;;;OAIG;IACH,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;CAC1B"}

package/dist/neutral/modules/protocol-model/index.d.ts

@@ -10,6 +10,7 @@ export * from './payload/index.js';
 export * from './provider/index.js';
 export * from './RecordKeyType.js';
 export * from './rejection/index.js';
+export * from './signature/index.js';
 export * from './Step/index.js';
 export * from './transaction/index.js';
 export * from './TransferPayload.js';

package/dist/neutral/modules/protocol-model/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/protocol-model/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/protocol-model/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA"}

package/dist/neutral/modules/protocol-model/signature/canonicalSignature.d.ts

@@ -0,0 +1,39 @@
+/** Order of the secp256k1 curve. */
+export declare const SECP256K1_N = 115792089237316195423570985008687907852837564279074904382605163141518161494337n;
+/** Largest `s` value accepted as canonical (low-S). */
+export declare const SECP256K1_HALF_N: bigint;
+/**
+ * Reads the `s` component of a hex-encoded compact secp256k1 signature.
+ *
+ * @param signature - Compact signature as hex (128 characters, optionally `0x`-prefixed)
+ * @returns The `s` scalar, or `undefined` when the input is not a compact signature
+ */
+export declare function signatureS(signature: string): bigint | undefined;
+/**
+ * Whether a compact secp256k1 signature uses the canonical (low-S) form.
+ *
+ * secp256k1 signatures are malleable: for any valid `(r, s)` the twin
+ * `(r, n - s)` is an equally valid signature over the same message by the same
+ * key. Accepting both means one signed object has two valid encodings — and
+ * therefore two different `_hash` values, while its `_dataHash` is unchanged.
+ * Requiring `s <= n / 2` makes the encoding unique.
+ *
+ * Signatures produced by the XYO SDK are always low-S, so this rejects nothing
+ * that was honestly signed.
+ *
+ * @param signature - Compact signature as hex (128 characters, optionally `0x`-prefixed)
+ * @returns `true` when `s` is non-zero and in the lower half of the curve order
+ */
+export declare function isCanonicalSignature(signature: unknown): boolean;
+/**
+ * Returns the canonical (low-S) form of a compact secp256k1 signature.
+ *
+ * An already-canonical signature is returned unchanged; a high-S signature is
+ * rewritten as `(r, n - s)`, which is equally valid and recovers the same
+ * address. A value that is not a compact signature is returned unchanged.
+ *
+ * @param signature - Compact signature as hex (128 characters, optionally `0x`-prefixed)
+ * @returns The signature in canonical low-S form, preserving any `0x` prefix
+ */
+export declare function normalizeSignature(signature: string): string;
+//# sourceMappingURL=canonicalSignature.d.ts.map

package/dist/neutral/modules/protocol-model/signature/canonicalSignature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalSignature.d.ts","sourceRoot":"","sources":["../../../../../src/modules/protocol-model/signature/canonicalSignature.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,eAAO,MAAM,WAAW,kFAAqG,CAAA;AAE7H,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,QAAmB,CAAA;AAYhD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAIhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAO5D"}

package/dist/neutral/modules/protocol-model/signature/index.d.ts

@@ -0,0 +1,2 @@
+export * from './canonicalSignature.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/modules/protocol-model/signature/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/protocol-model/signature/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA"}

package/dist/neutral/modules/validation/block/validators/BlockTransactionUniquenessValidator.d.ts

@@ -0,0 +1,23 @@
+import type { HydratedBlockStateValidationFunction } from '../../../protocol-lib/index.js';
+/**
+ * Creates a block state validator that rejects a block which would execute the same signed
+ * authorization more than once, or which carries a malleated signature.
+ *
+ * Two checks, both keyed on signature-independent identity:
+ *
+ * 1. **Duplicate effects.** Transactions are deduplicated by `_dataHash`, not `_hash`. A
+ *    transaction's `_hash` covers its `$signatures`; `_dataHash` does not. Because secp256k1
+ *    signatures are malleable, any observer of a signed transaction can derive the twin
+ *    `(r, n - s)` without the sender's private key. That twin is a *different* `_hash` over
+ *    the *same* `_dataHash`, so a check keyed on `_hash` treats it as a new transaction and
+ *    lets the transfer execute a second time.
+ *
+ * 2. **Non-canonical signatures.** A high-S signature is, by construction, such a twin.
+ *    Rejecting it at block level keeps a malleated transaction out of the chain even if it
+ *    slipped past mempool admission.
+ *
+ * Chain engines must inject this alongside `BlockCumulativeBalanceValidatorFactory` — see the
+ * note on `validateTransaction` about `additionalValidators`.
+ */
+export declare function BlockTransactionUniquenessValidatorFactory(): HydratedBlockStateValidationFunction;
+//# sourceMappingURL=BlockTransactionUniquenessValidator.d.ts.map

package/dist/neutral/modules/validation/block/validators/BlockTransactionUniquenessValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockTransactionUniquenessValidator.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/block/validators/BlockTransactionUniquenessValidator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,eAAe,CAAA;AAOzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0CAA0C,IAAI,oCAAoC,CA2CjG"}

package/dist/neutral/modules/validation/block/validators/index.d.ts

@@ -1,2 +1,3 @@
 export * from './BlockCumulativeBalanceValidator.js';
+export * from './BlockTransactionUniquenessValidator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/neutral/modules/validation/block/validators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/block/validators/index.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/block/validators/index.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAA;AACpD,cAAc,0CAA0C,CAAA"}

package/dist/neutral/modules/validation/transaction/validateTransaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateTransaction.d.ts","sourceRoot":"","sources":["../../../../../src/modules/validation/transaction/validateTransaction.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qCAAqC,EAGtC,MAAM,eAAe,CAAA;AAStB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,qCAmCjC,CAAA"}
+{"version":3,"file":"validateTransaction.d.ts","sourceRoot":"","sources":["../../../../../src/modules/validation/transaction/validateTransaction.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qCAAqC,EAGtC,MAAM,eAAe,CAAA;AAUtB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,qCAoCjC,CAAA"}

package/dist/neutral/modules/validation/transaction/validators/TransactionSignatureCanonicalityValidator.d.ts

@@ -0,0 +1,22 @@
+import type { HydratedTransactionValidationFunction } from '../../../protocol-lib/index.js';
+/**
+ * Rejects transactions carrying a non-canonical (high-S) secp256k1 signature.
+ *
+ * secp256k1 signatures are malleable: for a valid `(r, s)` the twin `(r, n - s)`
+ * is an equally valid signature over the same data by the same key. Because a
+ * transaction's `_hash` covers `$signatures` while its `_dataHash` does not, an
+ * observer who sees a signed transaction can derive that twin without the
+ * sender's private key and submit it as a *different* transaction with the
+ * *same* effects — replaying the transfer.
+ *
+ * Every signature produced by the XYO SDK is already low-S (libsecp256k1
+ * normalizes when signing), so this rule rejects no honestly signed
+ * transaction. It is enforced here, at the protocol layer, so a chain stays
+ * protected even when running against an SDK build that still accepts the twin.
+ *
+ * Dropping the twin at admission is necessary but not sufficient on its own:
+ * see `TransactionDataHashUniquenessValidator` for the inclusion-side check
+ * that catches any duplicate effect regardless of how the signature differs.
+ */
+export declare const TransactionSignatureCanonicalityValidator: HydratedTransactionValidationFunction;
+//# sourceMappingURL=TransactionSignatureCanonicalityValidator.d.ts.map

package/dist/neutral/modules/validation/transaction/validators/TransactionSignatureCanonicalityValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionSignatureCanonicalityValidator.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/transaction/validators/TransactionSignatureCanonicalityValidator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qCAAqC,EAAmC,MAAM,eAAe,CAAA;AAM3G;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yCAAyC,EAAE,qCAqBvD,CAAA"}

package/dist/neutral/modules/validation/transaction/validators/index.d.ts

@@ -6,5 +6,6 @@ export * from './TransactionFromValidator.js';
 export * from './TransactionGasValidator.js';
 export * from './TransactionJsonSchemaValidator.js';
 export * from './TransactionProtocolValidator.js';
+export * from './TransactionSignatureCanonicalityValidator.js';
 export * from './TransactionTransfersValidator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/neutral/modules/validation/transaction/validators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/transaction/validators/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,uCAAuC,CAAA;AACrD,cAAc,mCAAmC,CAAA;AACjD,cAAc,oCAAoC,CAAA;AAClD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,mCAAmC,CAAA;AACjD,cAAc,oCAAoC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/validation/transaction/validators/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,uCAAuC,CAAA;AACrD,cAAc,mCAAmC,CAAA;AACjD,cAAc,oCAAoC,CAAA;AAClD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,mCAAmC,CAAA;AACjD,cAAc,gDAAgD,CAAA;AAC9D,cAAc,oCAAoC,CAAA"}