@polymeshassociation/polymesh-sdk 31.0.0 → 31.1.0-beta.2

package/base/ethTransaction.js

@@ -0,0 +1,317 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEthSubmissionStrategy = getEthSubmissionStrategy;
+exports.supportsEip1559 = supportsEip1559;
+exports.dryRunEthTransaction = dryRunEthTransaction;
+exports.buildEthTransactionRequest = buildEthTransactionRequest;
+exports.buildDetachedEthTransactionRequest = buildDetachedEthTransactionRequest;
+exports.calculateEthGasFee = calculateEthGasFee;
+exports.getNativeToEthRatio = getNativeToEthRatio;
+exports.ethTransactKeccakMatcher = ethTransactKeccakMatcher;
+exports.buildSdkBroadcastSubmission = buildSdkBroadcastSubmission;
+exports.buildWalletBroadcastSubmission = buildWalletBroadcastSubmission;
+const util_crypto_1 = require("@polkadot/util-crypto");
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const utils_1 = require("../base/utils");
+const internal_1 = require("../internal");
+const types_1 = require("../types");
+const conversion_1 = require("../utils/conversion");
+const eth_1 = require("../utils/eth");
+/**
+ * @hidden
+ *
+ * Resolve how to submit for the given signer, from the methods it actually implements.
+ *
+ * `signTransaction` wins when a signer implements both, since it lets the SDK keep control of the
+ *   nonce and of the full submission lifecycle
+ *
+ * @note the returned method is bound to the signer. Callers have to destructure it to narrow the
+ *   optional property, which would otherwise silently drop `this` for any signer implementing the
+ *   interface with ordinary class methods rather than arrow function properties
+ *
+ * @throws if the signer implements neither method
+ */
+function getEthSubmissionStrategy(ethSigner) {
+    const { signTransaction, sendTransaction } = ethSigner;
+    if (signTransaction) {
+        return { mode: 'sdkBroadcast', signTransaction: signTransaction.bind(ethSigner) };
+    }
+    if (sendTransaction) {
+        return { mode: 'walletBroadcast', sendTransaction: sendTransaction.bind(ethSigner) };
+    }
+    throw new internal_1.PolymeshError({
+        code: types_1.ErrorCode.General,
+        message: 'The attached Ethereum signer implements neither signTransaction nor sendTransaction, so it cannot submit a transaction. Please report this to the Polymesh team',
+    });
+}
+/**
+ * @hidden
+ *
+ * Whether to build an EIP-1559 (type 2) transaction for the given signer. Defaults to `true`, so
+ *   a signer only has to declare the capability when it *cannot* encode type 2
+ */
+function supportsEip1559(ethSigner) {
+    var _a;
+    return (_a = ethSigner.capabilities.eip1559) !== null && _a !== void 0 ? _a : true;
+}
+/**
+ * @hidden
+ *
+ * `0x`-prefixed, minimal (no leading zeros) hex "quantity" encoding, as used throughout the
+ *   Ethereum JSON-RPC spec for `gas`, `gasPrice`, `chainId`, `nonce`, etc
+ */
+function toQuantityHex(value) {
+    return `0x${value.integerValue(bignumber_js_1.default.ROUND_FLOOR).toString(16)}`;
+}
+/**
+ * @hidden
+ *
+ * Perform the mandatory dry run pre-flight for a Polymesh call carried through the
+ *   `revive` pallet's sentinel address. This is the SDK's only pre-flight signal, and doing it
+ *   over the Substrate connection means a structured error arrives before the wallet is ever
+ *   consulted
+ *
+ * Split out from {@link buildEthTransactionRequest} so that fee estimation
+ *   ({@link base/PolymeshTransactionBase!PolymeshTransactionBase.getTotalFees | getTotalFees}) can
+ *   use it without requiring an {@link EthSigner} to be attached
+ *
+ * @throws the parsed dry run error (via {@link utils/eth!parseEthTransactError}) if the dry run itself fails
+ */
+function dryRunEthTransaction(context, signingAddress, composedTx) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { polymeshApi: { call }, } = context;
+        const from = (0, eth_1.ethAddressFromSs58)(signingAddress, context.ss58Format);
+        const [to, gasPriceRaw] = yield Promise.all([
+            context.getEthRuntimePalletsAddress(),
+            call.reviveApi.gasPrice(),
+        ]);
+        const chainId = context.getEthChainId();
+        const calldata = composedTx.method.toHex();
+        const gasPrice = new bignumber_js_1.default(gasPriceRaw.toString());
+        const dryRun = yield call.reviveApi.ethTransactWithConfig({
+            from,
+            to,
+            input: { data: calldata },
+            value: 0,
+        }, {});
+        if (dryRun.isErr) {
+            throw (0, eth_1.parseEthTransactError)(dryRun.asErr, context);
+        }
+        const { ethGas: rawEthGasCodec } = dryRun.asOk;
+        const rawEthGas = new bignumber_js_1.default(rawEthGasCodec.toString());
+        return { from: from, to: to, calldata, rawEthGas, gasPrice, chainId };
+    });
+}
+/**
+ * @hidden
+ *
+ * Build the {@link EthTransactionRequest} that carries a Polymesh runtime call through the
+ *   `revive` pallet's sentinel address, performing the mandatory dry run pre-flight along the
+ *   way
+ *
+ * @throws
+ * - the parsed dry run error (via {@link utils/eth!parseEthTransactError}) if the dry run itself fails
+ * - `ValidationError` if `nonce` is passed while the signer can only broadcast, and so owns the
+ *   nonce itself
+ */
+function buildEthTransactionRequest(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { context, signingAddress, composedTx, ethSigner, nonce: nonceOverride, gasMultiplier = new bignumber_js_1.default(1), } = params;
+        const { mode } = getEthSubmissionStrategy(ethSigner);
+        if (mode === 'walletBroadcast' && nonceOverride) {
+            throw new internal_1.PolymeshError({
+                code: types_1.ErrorCode.ValidationError,
+                message: 'The nonce cannot be set explicitly when the Ethereum signer broadcasts the transaction itself. The wallet is responsible for nonce management in this mode',
+            });
+        }
+        const { from, to, calldata, rawEthGas, gasPrice, chainId } = yield dryRunEthTransaction(context, signingAddress, composedTx);
+        const gasToUse = bignumber_js_1.default.max(rawEthGas.multipliedBy(gasMultiplier).integerValue(bignumber_js_1.default.ROUND_CEIL), rawEthGas);
+        let nonce;
+        if (mode === 'sdkBroadcast') {
+            if (nonceOverride) {
+                nonce = toQuantityHex(nonceOverride);
+            }
+            else {
+                const { polymeshApi: { call }, } = context;
+                const onChainNonce = yield call.reviveApi.nonce(from);
+                nonce = toQuantityHex(new bignumber_js_1.default(onChainNonce.toString()));
+            }
+        }
+        const eip1559 = supportsEip1559(ethSigner);
+        const request = Object.assign(Object.assign({ from,
+            to, data: calldata, value: '0x0', gas: toQuantityHex(gasToUse), chainId: toQuantityHex(chainId) }, (nonce ? { nonce } : {})), (eip1559
+            ? {
+                type: '0x2',
+                maxFeePerGas: toQuantityHex(gasPrice),
+                maxPriorityFeePerGas: toQuantityHex(new bignumber_js_1.default(0)),
+            }
+            : {
+                type: '0x0',
+                gasPrice: toQuantityHex(gasPrice),
+            }));
+        return { request, rawEthGas, gasPrice };
+    });
+}
+/**
+ * @hidden
+ *
+ * Build an {@link EthTransactionRequest} for detached/custody signing
+ * ({@link base/PolymeshTransactionBase!PolymeshTransactionBase.toEthSignablePayload | toEthSignablePayload}),
+ *   where there is no {@link EthSigner} attached to consult for routing. The nonce is always
+ *   resolved (either the caller's `ProcedureOpts.nonce`, or fetched on-chain), since a detached
+ *   signer cannot own the nonce the way a broadcasting wallet does
+ */
+function buildDetachedEthTransactionRequest(context, signingAddress, composedTx, eip1559, nonceOverride) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { from, to, calldata, rawEthGas, gasPrice, chainId } = yield dryRunEthTransaction(context, signingAddress, composedTx);
+        let nonce;
+        if (nonceOverride) {
+            nonce = toQuantityHex(nonceOverride);
+        }
+        else {
+            const { polymeshApi: { call }, } = context;
+            const onChainNonce = yield call.reviveApi.nonce(from);
+            nonce = toQuantityHex(new bignumber_js_1.default(onChainNonce.toString()));
+        }
+        return Object.assign({ from,
+            to, data: calldata, value: '0x0', gas: toQuantityHex(rawEthGas), chainId: toQuantityHex(chainId), nonce }, (eip1559
+            ? {
+                type: '0x2',
+                maxFeePerGas: toQuantityHex(gasPrice),
+                maxPriorityFeePerGas: toQuantityHex(new bignumber_js_1.default(0)),
+            }
+            : {
+                type: '0x0',
+                gasPrice: toQuantityHex(gasPrice),
+            }));
+    });
+}
+/**
+ * @hidden
+ *
+ * Derive the network fee for a transaction submitted through the `revive` pallet's sentinel
+ *   address:
+ *
+ * ```
+ * feeInBaseUnits = ethGas * gasPrice / nativeToEthRatio
+ * ```
+ *
+ * The result is returned as a **display POLYX value**, i.e. shifted down by the chain's 6
+ *   decimals, so that it is directly comparable with everything else in `PayingAccountFees` —
+ *   protocol fees and Account balances both arrive that way, via `balanceToBigNumber`. Returning
+ *   base units here would make the Ethereum path report fees 10^6 too large, and every fee check
+ *   against a balance would fail
+ *
+ * @note the rounding is applied to whole base units *before* the shift, since a fee cannot be a
+ *   fraction of a base unit
+ * @note this is a slight, safe overestimate of the fee the chain actually charges — measured at
+ *   1.008-1.011x. It does **not** include protocol fees, which are charged separately and must
+ *   still be summed in by the caller
+ */
+function calculateEthGasFee(rawEthGas, gasPrice, nativeToEthRatio) {
+    return rawEthGas
+        .multipliedBy(gasPrice)
+        .dividedBy(nativeToEthRatio)
+        .integerValue(bignumber_js_1.default.ROUND_CEIL)
+        .shiftedBy(-6);
+}
+/**
+ * @hidden
+ *
+ * Retrieve `consts.revive.nativeToEthRatio` as a `BigNumber`
+ */
+function getNativeToEthRatio(context) {
+    return (0, conversion_1.u64ToBigNumber)(context.polymeshApi.consts.revive.nativeToEthRatio);
+}
+/**
+ * @hidden
+ *
+ * Build the predicate that correlates an Ethereum transaction hash (returned by a broadcasting
+ *   wallet's `sendTransaction`) to the Substrate extrinsic that carries it:
+ *
+ * ```
+ * extrinsic.method.section === 'revive' &&
+ * extrinsic.method.method === 'ethTransact' &&
+ * keccakAsHex(extrinsic.args[0].toU8a(true)) === ethTxHash
+ * ```
+ *
+ * This is deterministic, not a heuristic: the Ethereum transaction hash is `keccak256` of the raw
+ *   signed transaction, and those exact bytes are the `payload` argument of the `revive.ethTransact`
+ *   extrinsic recorded in the block — byte-identical, including in blocks carrying several
+ *   Ethereum extrinsics
+ */
+function ethTransactKeccakMatcher(ethTxHash) {
+    const normalizedHash = ethTxHash.toLowerCase();
+    return (extrinsic) => {
+        if (extrinsic.method.section !== 'revive' || extrinsic.method.method !== 'ethTransact') {
+            return false;
+        }
+        const [payload] = extrinsic.args;
+        if (!payload) {
+            return false;
+        }
+        return (0, util_crypto_1.keccakAsHex)(payload.toU8a(true)).toLowerCase() === normalizedHash;
+    };
+}
+/**
+ * @hidden
+ *
+ * The SDK holds the raw signed bytes and submits them itself via
+ *   `api.tx.revive.ethTransact(raw)`. Since this is a *bare* (unsigned) extrinsic — the
+ *   signature is embedded in the Ethereum payload itself — it is broadcast with `.send()`
+ *   rather than `.signAndSend()`, exactly like the offline-signed path in
+ *   `Network.submitTransaction`. From here on, the lifecycle is identical to the native path:
+ *   same `ISubmittableResult` status transitions, same `outer.hash` semantics
+ */
+function buildSdkBroadcastSubmission(context, rawSignedTx) {
+    const outer = context.polymeshApi.tx.revive.ethTransact(rawSignedTx);
+    return {
+        subscription: {
+            subscribe: callback => outer.send(callback),
+            getTxHash: () => outer.hash.toString(),
+        },
+        polling: {
+            send: () => __awaiter(this, void 0, void 0, function* () {
+                const txHash = yield outer.send();
+                return { txHash: txHash.toString(), matcher: (0, utils_1.extrinsicHashMatcher)(txHash) };
+            }),
+        },
+    };
+}
+/**
+ * @hidden
+ *
+ * The wallet signs AND broadcasts, returning the Ethereum transaction hash.
+ *   The SDK never submits anything itself here, so there is no extrinsic-status subscription
+ *   channel to attach to — the only way to locate the result is to scan blocks for the matching
+ *   `revive.ethTransact` extrinsic (via {@link ethTransactKeccakMatcher}).
+ *
+ * The block scan is shared with the native path rather than duplicated: the same
+ *   {@link ExtrinsicMatcher} drives both, so there is one implementation and one set of tests
+ *
+ * @param sendTransaction - the signer's `sendTransaction`, resolved by the caller. Taking the
+ *   bound method rather than the signer is what makes this total: reaching here at all means
+ *   {@link getEthSubmissionStrategy} found the method, so there is no "signer said it could broadcast
+ *   but cannot" case left to guard against
+ */
+function buildWalletBroadcastSubmission(sendTransaction, request) {
+    return {
+        send: () => __awaiter(this, void 0, void 0, function* () {
+            const ethTxHash = yield sendTransaction(request);
+            return { txHash: ethTxHash, matcher: ethTransactKeccakMatcher(ethTxHash) };
+        }),
+    };
+}
+//# sourceMappingURL=ethTransaction.js.map

package/base/ethTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ethTransaction.js","sourceRoot":"","sources":["../../src/base/ethTransaction.ts"],"names":[],"mappings":"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"}

package/base/types.d.ts

@@ -1,17 +1,60 @@
 import { SignerPayloadJSON, SignerPayloadRaw, TypeDef } from '@polkadot/types/types';
 import { HexString } from '@polkadot/util/types';
+import { EthTransactionRequest } from '@polymeshassociation/signing-manager-types';
 import BigNumber from 'bignumber.js';
 import { PolymeshError as PolymeshErrorClass } from '../base/PolymeshError';
 import { PolymeshTransaction as PolymeshTransactionClass } from '../base/PolymeshTransaction';
 import { PolymeshTransactionBatch as PolymeshTransactionBatchClass } from '../base/PolymeshTransactionBatch';
 import { Account } from '../internal';
-import { Fees, TxData } from '../types';
+import { Fees, TxData, TxTag } from '../types';
 /**
  * Apply the {@link TxData} type to all args in an array
  */
 export type MapTxData<ArgsArray extends unknown[][]> = {
     [K in keyof ArgsArray]: ArgsArray[K] extends unknown[] ? TxData<ArgsArray[K]> : never;
 };
+/**
+ * Handle to a transaction that has been broadcast but is not being tracked. Returned by
+ *   {@link base/PolymeshTransactionBase!PolymeshTransactionBase.broadcast | transaction.broadcast},
+ *   which is `run` split at its natural seam: the transaction is on its way to the chain, and
+ *   whether to wait for it is now the caller's decision
+ */
+export interface TransactionBroadcastHandle<ReturnValue> {
+    /**
+     * the hash the transaction can be looked up by. Normally the Substrate extrinsic hash, but the
+     *   Ethereum transaction hash when an Ethereum wallet broadcast it, since that is the handle the
+     *   user has and can find in a block explorer
+     */
+    txHash: string;
+    /**
+     * the Ethereum transaction hash, set only when an Ethereum wallet broadcast the transaction
+     *   itself. `undefined` otherwise
+     */
+    ethTxHash?: string;
+    /**
+     * the block height the search for this transaction has to start from. Persist this alongside
+     *   `txHash` to resume tracking later via
+     *   {@link api/client/Network!Network.watchTransaction | network.watchTransaction}, for example
+     *   after a page reload, when `watch` itself is long gone
+     */
+    startingBlock: BigNumber;
+    /**
+     * Wait for the transaction to be included in a finalized block and return the same value
+     *   `run` would have returned
+     *
+     * Safe to retry if it times out — nothing is resubmitted, the search simply resumes. Calling it
+     *   while a previous call is still in flight throws
+     *
+     * @param opts.timeout - milliseconds to wait before giving up. Overrides `submission.watchTimeout`
+     *   from the Procedure options. Defaults to waiting indefinitely
+     *
+     * @throws `TransactionTimeout` if the transaction is not found in time. The transaction was still
+     *   broadcast and may yet be included — this reports only that the SDK stopped looking
+     */
+    watch: (opts?: {
+        timeout?: number;
+    }) => Promise<ReturnValue>;
+}
 export declare enum TransactionStatus {
     /**
      * the transaction is prepped to run
@@ -193,4 +236,26 @@ export type TransactionPayloadInput = TransactionPayload | TransactionPayload['p
 export type PolymeshTransaction<ReturnValue = unknown, TransformedReturnValue = ReturnValue, Args extends unknown[] | [] = unknown[]> = PolymeshTransactionClass<ReturnValue, TransformedReturnValue, Args>;
 export type PolymeshTransactionBatch<ReturnValue = unknown, TransformedReturnValue = ReturnValue, Args extends unknown[][] = unknown[][]> = PolymeshTransactionBatchClass<ReturnValue, TransformedReturnValue, Args>;
 export type PolymeshError = PolymeshErrorClass;
+export { EthSigner, EthSignerCapabilities, EthSigningManager, } from '@polymeshassociation/signing-manager-types';
+export { EthTransactionRequest };
+/**
+ * A representation of an Ethereum transaction intended for offline/detached signing, along with
+ *   the decoded call for display
+ */
+export interface EthTransactionPayload {
+    /**
+     * the parameters that would be passed to `EthSigner.signTransaction` / `sendTransaction`
+     *
+     * @note every field is 0x-prefixed hex, never a number or bigint. ethers and viem both need it
+     *   converted first — `@polymeshassociation/eth-signing-manager` exports `toEthersTransaction` /
+     *   `toViemTransaction` for that, usable without the manager itself
+     */
+    transaction: EthTransactionRequest;
+    /** the transaction tag identifying the underlying Polymesh call */
+    tag: TxTag;
+    /** argument metadata for the underlying Polymesh call */
+    args: TransactionArgument[];
+    /** additional information attached to the payload, such as IDs or memos about the transaction */
+    metadata: Record<string, string>;
+}
 //# sourceMappingURL=types.d.ts.map

package/base/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/base/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/base/types.ts"],"names":[],"mappings":"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"}

package/base/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/base/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;;;AAmB/D,IAAY,iBAsCX;AAtCD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,kCAAa,CAAA;IACb;;OAEG;IACH,8CAAyB,CAAA;IACzB;;OAEG;IACH,wCAAmB,CAAA;IACnB;;OAEG;IACH,wCAAmB,CAAA;IACnB;;OAEG;IACH,sCAAiB,CAAA;IACjB;;OAEG;IACH,0CAAqB,CAAA;IACrB;;OAEG;IACH,4CAAuB,CAAA;IACvB;;OAEG;IACH,sCAAiB,CAAA;IACjB;;;OAGG;IACH,wCAAmB,CAAA;AACrB,CAAC,EAtCW,iBAAiB,iCAAjB,iBAAiB,QAsC5B;AAED,IAAY,uBAeX;AAfD,WAAY,uBAAuB;IACjC,sCAAW,CAAA;IACX,8CAAmB,CAAA;IACnB,wCAAa,CAAA;IACb,8CAAmB,CAAA;IACnB,4CAAiB,CAAA;IACjB,8CAAmB,CAAA;IACnB,wCAAa,CAAA;IACb,0CAAe,CAAA;IACf,0CAAe,CAAA;IACf,oDAAyB,CAAA;IACzB,gDAAqB,CAAA;IACrB,4CAAiB,CAAA;IACjB,8CAAmB,CAAA;IACnB,wCAAa,CAAA;AACf,CAAC,EAfW,uBAAuB,uCAAvB,uBAAuB,QAelC;AA0CD;;GAEG;AACH,IAAY,iBAmBX;AAnBD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,wCAAmB,CAAA;IACnB;;;;OAIG;IACH,oCAAe,CAAA;IACf;;OAEG;IACH,sCAAiB,CAAA;IACjB;;OAEG;IACH,wDAAmC,CAAA;AACrC,CAAC,EAnBW,iBAAiB,iCAAjB,iBAAiB,QAmB5B"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/base/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;;;AAgE/D,IAAY,iBAsCX;AAtCD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,kCAAa,CAAA;IACb;;OAEG;IACH,8CAAyB,CAAA;IACzB;;OAEG;IACH,wCAAmB,CAAA;IACnB;;OAEG;IACH,wCAAmB,CAAA;IACnB;;OAEG;IACH,sCAAiB,CAAA;IACjB;;OAEG;IACH,0CAAqB,CAAA;IACrB;;OAEG;IACH,4CAAuB,CAAA;IACvB;;OAEG;IACH,sCAAiB,CAAA;IACjB;;;OAGG;IACH,wCAAmB,CAAA;AACrB,CAAC,EAtCW,iBAAiB,iCAAjB,iBAAiB,QAsC5B;AAED,IAAY,uBAeX;AAfD,WAAY,uBAAuB;IACjC,sCAAW,CAAA;IACX,8CAAmB,CAAA;IACnB,wCAAa,CAAA;IACb,8CAAmB,CAAA;IACnB,4CAAiB,CAAA;IACjB,8CAAmB,CAAA;IACnB,wCAAa,CAAA;IACb,0CAAe,CAAA;IACf,0CAAe,CAAA;IACf,oDAAyB,CAAA;IACzB,gDAAqB,CAAA;IACrB,4CAAiB,CAAA;IACjB,8CAAmB,CAAA;IACnB,wCAAa,CAAA;AACf,CAAC,EAfW,uBAAuB,uCAAvB,uBAAuB,QAelC;AA0CD;;GAEG;AACH,IAAY,iBAmBX;AAnBD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,wCAAmB,CAAA;IACnB;;;;OAIG;IACH,oCAAe,CAAA;IACf;;OAEG;IACH,sCAAiB,CAAA;IACjB;;OAEG;IACH,wDAAmC,CAAA;AACrC,CAAC,EAnBW,iBAAiB,iCAAjB,iBAAiB,QAmB5B"}

package/base/utils.d.ts

@@ -1,7 +1,8 @@
 import { SubmittableResult } from '@polkadot/api';
+import { GenericExtrinsic } from '@polkadot/types';
 import { DispatchError, Hash } from '@polkadot/types/interfaces';
 import { SpRuntimeDispatchError } from '../../node_modules/@polymeshassociation/polymesh-types/polkadot/types-lookup';
-import { TypeDef } from '@polkadot/types/types';
+import { ISubmittableResult, TypeDef } from '@polkadot/types/types';
 import { BigNumber } from 'bignumber.js';
 import { Context, PolymeshError } from '../internal';
 import { TransactionArgument, TxTag } from '../types';
@@ -11,25 +12,73 @@ export declare const dispatchErrorToMessage: (error: SpRuntimeDispatchError | Di
  * @hidden
  */
 export declare const handleExtrinsicFailure: (error: SpRuntimeDispatchError, data?: Record<string, unknown>) => PolymeshError;
-export declare const handleTransactionSubmissionError: (err: Error) => PolymeshError;
 /**
  * @hidden
  *
- * given a transaction hash this will poll the chain until it is included in a finalized block
+ * Inspect a transaction receipt for an on-chain failure and return the corresponding error, or
+ *   `undefined` if the transaction succeeded
+ *
+ * Two distinct failure shapes feed into the same {@link handleExtrinsicFailure}:
+ *
+ * - `system.ExtrinsicFailed`, the native path's failure signal
+ * - `revive.EthExtrinsicRevert`, emitted instead on the Ethereum signing path. There, the outer
+ *   `revive.ethTransact` extrinsic still emits `system.ExtrinsicSuccess` even when the inner
+ *   dispatch failed, so this check must run (and take priority) before the receipt is otherwise
+ *   treated as a success
+ */
+export declare const getExtrinsicFailure: (receipt: ISubmittableResult) => PolymeshError | undefined;
+export declare const handleTransactionSubmissionError: (err: Error) => PolymeshError;
+/**
+ * @hidden
  *
- * @note this method should only be used when there is no subscription support for efficiency
+ * Predicate used to recognize a submitted transaction within a block's body. The native path
+ *   matches on the extrinsic hash, while Ethereum signed transactions match on the keccak hash
+ *   of the `revive.ethTransact` payload (since the extrinsic itself is unsigned and its hash is
+ *   not known to the wallet that broadcast it)
+ */
+export type ExtrinsicMatcher = (extrinsic: GenericExtrinsic) => boolean;
+/**
+ * @hidden
  *
- * @throws if transaction is not found after a certain amount of time
+ * Build a matcher that recognizes an extrinsic by its hash. This is the native submission path
+ */
+export declare const extrinsicHashMatcher: (txHash: Hash) => ExtrinsicMatcher;
+/**
+ * @hidden
  *
- * @param txHash The hash of the transaction
- * @param startingBlock The block number from before the transaction was submitted
- * @param context
- * @param pollOptions Controls max time to poll, defaults should be OK (finalization takes ~15 seconds)
- * @returns
+ * Where a transaction was found, reported as soon as it is included in a block — before that
+ *   block is finalized
  */
-export declare const pollForTransactionFinalization: (txHash: Hash, startingBlock: BigNumber, context: Context, pollOptions?: {
+export interface TransactionInclusionInfo {
+    blockHash: string;
+    blockNumber: BigNumber;
+    txIndex: number;
+}
+export declare const pollForTransactionFinalization: (matcher: ExtrinsicMatcher, startingBlock: BigNumber, context: Context, pollOptions?: {
     delayMs: number;
     maxAttempts: number;
+}, onInBlock?: (info: TransactionInclusionInfo) => void) => Promise<SubmittableResult>;
+/**
+ * @hidden
+ *
+ * Locate a submitted transaction by subscribing to the chain's blocks, rather than polling for
+ *   them. Preferred whenever the connection supports subscriptions: inclusion is reported the
+ *   moment the block arrives instead of on the next poll tick, and it removes a repeating
+ *   `getHeader`/`getBlock` cycle per in-flight transaction
+ *
+ * Two independent scans run off two subscriptions:
+ *
+ * - **new heads** are advisory. They exist only to report inclusion early, via `onInBlock`. A
+ *   block seen here may still be re-organised away, which is harmless because nothing but a
+ *   progress callback depends on it
+ * - **finalized heads** are authoritative. The resolved result always comes from a finalized
+ *   block, so a re-org cannot produce a wrong result — the transaction simply will not be found
+ *   at that height on the canonical chain, and the scan continues
+ *
+ * @throws if the transaction is not found within `maxFinalizedBlocks` finalized blocks
+ */
+export declare const subscribeForTransactionFinalization: (matcher: ExtrinsicMatcher, startingBlock: BigNumber, context: Context, onInBlock?: (info: TransactionInclusionInfo) => void, { maxFinalizedBlocks }?: {
+    maxFinalizedBlocks: number;
 }) => Promise<SubmittableResult>;
 /**
  * @hidden

package/base/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/base/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,IAAI,EAAe,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAiB,OAAO,EAAe,MAAM,uBAAuB,CAAC;AAE5E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAOL,mBAAmB,EAEnB,KAAK,EACN,MAAM,SAAS,CAAC;AA8CjB,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,EAAE,MAAM,MAAM,KAAG,mBAsF5D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO,sBAAsB,GAAG,aAAa,KAAG,MAgBtF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,sBAAsB,EAC7B,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,aAKF,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAI,KAAK,KAAK,KAAG,aAY7D,CAAC;AA4CF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,GACzC,QAAQ,IAAI,EACZ,eAAe,SAAS,EACxB,SAAS,OAAO,EAChB;;;CAAgD,KAC/C,OAAO,CAAC,iBAAiB,CAiD3B,CAAC;AAYF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,KAAK,KAAG,OAE/C,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/base/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAuB,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAiB,OAAO,EAAe,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAOL,mBAAmB,EAEnB,KAAK,EAEN,MAAM,SAAS,CAAC;AA8CjB,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,EAAE,MAAM,MAAM,KAAG,mBAsF5D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO,sBAAsB,GAAG,aAAa,KAAG,MAyCtF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,sBAAsB,EAC7B,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,aAKF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,kBAAkB,KAAG,aAAa,GAAG,SAmBjF,CAAC;AA0BF,eAAO,MAAM,gCAAgC,GAAI,KAAK,KAAK,KAAG,aAY7D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAgBxE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,IAAI,KAAG,gBAEnD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AA8JD,eAAO,MAAM,8BAA8B,GACzC,SAAS,gBAAgB,EACzB,eAAe,SAAS,EACxB,SAAS,OAAO,EAChB;;;CAAkC,EAClC,YAAY,CAAC,IAAI,EAAE,wBAAwB,KAAK,IAAI,KACnD,OAAO,CAAC,iBAAiB,CAsE3B,CAAC;AASF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mCAAmC,GAC9C,SAAS,gBAAgB,EACzB,eAAe,SAAS,EACxB,SAAS,OAAO,EAChB,YAAY,CAAC,IAAI,EAAE,wBAAwB,KAAK,IAAI,EACpD;;CAAqD,KACpD,OAAO,CAAC,iBAAiB,CAwH3B,CAAC;AAYF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,KAAK,KAAG,OAE/C,CAAC"}