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

package/base/PolymeshTransactionBase.js

@@ -16,6 +16,7 @@ exports.PolymeshTransactionBase = void 0;
 /* eslint-disable simple-import-sort/imports */
 const events_1 = require("events");
 const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const ethTransaction_1 = require("../base/ethTransaction");
 const utils_1 = require("../base/utils");
 const internal_1 = require("../internal");
 const common_1 = require("../middleware/queries/common");
@@ -23,6 +24,7 @@ const types_1 = require("../types");
 const internal_2 = require("../types/internal");
 const constants_1 = require("../utils/constants");
 const conversion_1 = require("../utils/conversion");
+const eth_1 = require("../utils/eth");
 const internal_3 = require("../utils/internal");
 /**
  * @hidden
@@ -68,11 +70,12 @@ class PolymeshTransactionBase {
          * whether the queue has run or not (prevents re-running)
          */
         this.hasRun = false;
-        const { resolver, transformer, signingAddress, signer, paidForBy, mortality, multiSig, multiSigOpts, preRunValidation, } = transactionSpec;
+        const { resolver, transformer, signingAddress, signer, paidForBy, mortality, multiSig, multiSigOpts, submission, preRunValidation, } = transactionSpec;
         this.signingAddress = signingAddress;
         this.multiSig = multiSig !== null && multiSig !== void 0 ? multiSig : null;
         this.mortality = mortality;
         this.multiSigOpts = multiSigOpts !== null && multiSigOpts !== void 0 ? multiSigOpts : {};
+        this.submissionOpts = submission !== null && submission !== void 0 ? submission : {};
         this.signer = signer;
         this.context = context;
         this.paidForBy = paidForBy;
@@ -145,18 +148,7 @@ class PolymeshTransactionBase {
                 }
                 yield this.assertFeesCovered();
                 const receipt = yield this.internalRun();
-                this.receipt = receipt;
-                const { resolver, transformer = (val) => Promise.resolve(val), } = this;
-                let value;
-                if ((0, internal_2.isResolverFunction)(resolver)) {
-                    value = yield resolver(receipt);
-                }
-                else {
-                    value = resolver;
-                }
-                this._result = yield transformer(value);
-                this.updateStatus(types_1.TransactionStatus.Succeeded);
-                return this._result;
+                return yield this.resolveResult(receipt);
             }
             catch (err) {
                 this.handleRunError(err);
@@ -166,6 +158,149 @@ class PolymeshTransactionBase {
             }
         });
     }
+    /**
+     * Broadcast the transaction and return as soon as it has been accepted, without waiting for it
+     *   to be included in a block. This is {@link run} split at its natural seam — the returned
+     *   handle's `watch` performs the second half and yields the exact value `run` would have — so
+     *   `await (await tx.broadcast()).watch()` is equivalent to `await tx.run()`
+     *
+     * Use it when waiting is not wanted, or not safe to depend on: an Ethereum wallet that
+     *   broadcasts on the user's behalf, a long finalization window a UI should not block on, or a
+     *   flow that persists the hash and resumes tracking later via
+     *   {@link api/client/Network!Network.watchTransaction | network.watchTransaction}
+     *
+     * @note this always submits without an extrinsic status subscription, since that channel cannot
+     *   report a hash without also waiting for the result. The trade-off is that `Future` status
+     *   reporting and in-pool `Aborted` detection are unavailable — those come from the node's
+     *   status stream, which only {@link run} attaches to
+     *
+     * @throws if the transaction has already been run or broadcast
+     * @throws `NotSupported` if the signing Account is a MultiSig signer. Use `runAsProposal`, which
+     *   needs the finalized receipt to report the resulting proposal
+     */
+    broadcast() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { context } = this;
+            if (this.hasRun) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.General,
+                    message: 'Cannot re-run a Transaction',
+                });
+            }
+            if (this.multiSig) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.NotSupported,
+                    message: '`.broadcast` cannot be used with a MultiSig signer, since the resulting proposal can only be read from the finalized transaction. `.runAsProposal` should be called instead',
+                    data: { signingAddress: this.signingAddress, multiSigAddress: this.multiSig.address },
+                });
+            }
+            try {
+                if (this.preRunValidation) {
+                    yield this.preRunValidation({ asProposal: false });
+                }
+                yield this.assertFeesCovered();
+                const startingBlock = yield context.getLatestBlock();
+                const { matcher } = yield this.broadcastToChain(yield this.buildPollingSubmission());
+                return Object.assign(Object.assign({ 
+                    // set by `broadcastToChain`, which cannot succeed without it
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    txHash: this.txHash }, (this.ethTxHash !== undefined ? { ethTxHash: this.ethTxHash } : {})), { startingBlock, watch: opts => this.watchBroadcast(matcher, startingBlock, opts === null || opts === void 0 ? void 0 : opts.timeout) });
+            }
+            catch (err) {
+                this.handleRunError(err);
+            }
+            finally {
+                /*
+                 * marked here rather than via `markAsRan`, which would also start the middleware sync. There
+                 *   is nothing for the middleware to have synced until `watch` sees a block, so that emit
+                 *   waits until then
+                 */
+                this.hasRun = true;
+            }
+        });
+    }
+    /**
+     * @hidden
+     *
+     * The second half of {@link broadcast}: wait for inclusion, then produce the same value `run`
+     *   would have. Retryable after a timeout, since nothing is resubmitted — the block scan simply
+     *   starts over from the same point
+     */
+    watchBroadcast(matcher, startingBlock, timeout) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isSuccess) {
+                // already watched to completion; scanning again would only rediscover the same block
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                return this._result;
+            }
+            if (this.watching) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.General,
+                    message: 'This transaction is already being watched. Await the promise returned by the previous `watch` call instead of starting another',
+                });
+            }
+            const watching = (() => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const receipt = yield this.watchForInclusion(matcher, startingBlock, timeout);
+                    const result = yield this.resolveResult(receipt);
+                    this.startMiddlewareSync();
+                    return result;
+                }
+                catch (err) {
+                    this.handleRunError(err);
+                }
+            }))();
+            this.watching = watching;
+            try {
+                return yield watching;
+            }
+            finally {
+                this.watching = undefined;
+            }
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Route to the polling-style submission for whichever signing path this transaction uses. The
+     *   returned function is what actually touches the signer, so that {@link broadcastToChain} can
+     *   bound it
+     */
+    buildPollingSubmission() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { signingAddress, context } = this;
+            yield context.assertHasSigningAddress(signingAddress);
+            if ((0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format)) {
+                const { ethSigner, request } = yield this.buildEthRequest();
+                return this.buildEthPollingSubmission((0, ethTransaction_1.getEthSubmissionStrategy)(ethSigner), request);
+            }
+            const { txWithArgs, signerOptions } = this.buildNativeSignerData();
+            return () => Promise.resolve(this.buildNativePollingSubmission(txWithArgs, signerOptions));
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Turn a finalized receipt into the value the caller gets back, recording it and moving the
+     *   transaction to `Succeeded`. Shared by `run` and by the `watch` returned from
+     *   {@link broadcast}, so that both produce the same value for the same transaction
+     */
+    resolveResult(receipt) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.receipt = receipt;
+            const { resolver, transformer = (val) => Promise.resolve(val), } = this;
+            let value;
+            if ((0, internal_2.isResolverFunction)(resolver)) {
+                value = yield resolver(receipt);
+            }
+            else {
+                value = resolver;
+            }
+            this._result = yield transformer(value);
+            this.updateStatus(types_1.TransactionStatus.Succeeded);
+            return this._result;
+        });
+    }
     /**
      * @hidden
      */
@@ -181,6 +316,14 @@ class PolymeshTransactionBase {
                 this.updateStatus(types_1.TransactionStatus.Rejected);
                 break;
             }
+            case types_1.ErrorCode.TransactionTimeout: {
+                /*
+                 * the transaction was not cancelled, the SDK merely stopped waiting for it. Moving to
+                 *   `Failed` would assert something untrue — it may still be included in a block — so the
+                 *   last observed status (`Running`, or `InBlock` if it was already seen) stands
+                 */
+                break;
+            }
             case types_1.ErrorCode.TransactionReverted:
             case types_1.ErrorCode.FatalError:
             default: {
@@ -195,6 +338,17 @@ class PolymeshTransactionBase {
      */
     markAsRan() {
         this.hasRun = true;
+        this.startMiddlewareSync();
+    }
+    /**
+     * @hidden
+     *
+     * Kick off the middleware sync notification. Separate from {@link markAsRan} because
+     *   {@link broadcast} marks the transaction as ran without having waited for a block — there is
+     *   nothing for the middleware to have synced yet at that point, so the emit waits until `watch`
+     *   completes
+     */
+    startMiddlewareSync() {
         /*
          * We do not await this promise because it is supposed to run in the background, and
          * any errors encountered are emitted. If the user isn't listening, they shouldn't
@@ -211,145 +365,373 @@ class PolymeshTransactionBase {
      */
     internalRun() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const { signingAddress, signer, mortality, context } = this;
+            const { signingAddress, context } = this;
             yield context.assertHasSigningAddress(signingAddress);
-            // era is how many blocks the transaction remains valid for, `undefined` for default
-            const era = mortality.immortal ? 0 : (_a = mortality.lifetime) === null || _a === void 0 ? void 0 : _a.toNumber();
-            const nonce = context.getNonce().toNumber();
-            this.updateStatus(types_1.TransactionStatus.Unapproved);
-            const txWithArgs = this.composeTx();
-            const signerOptions = Object.assign(Object.assign({ nonce, 
-                /*
-                 * allows signers (e.g. Ledger devices signing via the generic app) to return a modified
-                 *   `signedTransaction`, which is required when signed extensions like `CheckMetadataHash` alter the payload
-                 */
-                withSignedTransaction: true, 
-                /*
-                 * a returned `signedTransaction` may only alter signed extensions (e.g. `mode`, `metadataHash`).
-                 *   The API will reject any submission where the signer changed the call data itself
-                 */
-                allowCallDataAlteration: false }, (signer && { signer })), (era !== undefined ? { era } : {}));
+            if ((0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format)) {
+                return this.internalRunEth();
+            }
+            const { txWithArgs, signerOptions } = this.buildNativeSignerData();
             if (context.supportsSubscription()) {
-                return new Promise((resolve, reject) => {
-                    let settingBlockData = Promise.resolve();
-                    const gettingUnsub = txWithArgs.signAndSend(signingAddress, signerOptions, receipt => {
-                        const { status } = receipt;
-                        let isLastCallback = false;
-                        let unsubscribing = Promise.resolve();
-                        let extrinsicFailedEvent;
-                        if (status.isFuture) {
-                            this.updateStatus(types_1.TransactionStatus.Future);
-                        }
-                        else if (receipt.isCompleted) {
-                            // isCompleted implies status is one of: isFinalized, isInBlock or isError
-                            if (receipt.isInBlock) {
-                                const inBlockHash = status.asInBlock;
-                                /*
-                                 * this must be done to ensure that the block hash and number are set before the success event
-                                 *   is emitted, and at the same time. We do not resolve or reject the containing promise until this
-                                 *   one resolves
-                                 */
-                                settingBlockData = (0, internal_3.defusePromise)(this.context.polymeshApi.rpc.chain.getBlock(inBlockHash).then(({ block }) => {
-                                    this.blockHash = (0, conversion_1.hashToString)(inBlockHash);
-                                    this.blockNumber = (0, conversion_1.u32ToBigNumber)(block.header.number.unwrap());
-                                    // we know that the index has to be set by the time the transaction is included in a block
-                                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                                    this.txIndex = new bignumber_js_1.default(receipt.txIndex);
-                                    this.updateStatus(types_1.TransactionStatus.InBlock);
-                                }));
-                                // if the extrinsic failed due to an on-chain error, we should handle it in a special way
-                                [extrinsicFailedEvent] = (0, internal_3.filterEventRecords)(receipt, 'system', 'ExtrinsicFailed', true);
-                                // extrinsic failed so we can unsubscribe
-                                isLastCallback = !!extrinsicFailedEvent;
-                            }
-                            else {
-                                // isFinalized || isError so we know we can unsubscribe
-                                isLastCallback = true;
-                            }
-                            if (isLastCallback) {
-                                unsubscribing = gettingUnsub.then((unsub) => {
-                                    unsub();
-                                });
-                            }
-                            /*
-                             * Promise chain that handles all sub-promises in this pass through the signAndSend callback.
-                             * Primarily for consistent error handling
-                             */
-                            let finishing = Promise.resolve();
-                            if (extrinsicFailedEvent) {
-                                const { data } = extrinsicFailedEvent;
-                                finishing = Promise.all([settingBlockData, unsubscribing]).then(() => {
-                                    const error = (0, utils_1.handleExtrinsicFailure)(data[0]);
-                                    reject(error);
-                                });
-                            }
-                            else if (receipt.isFinalized) {
-                                finishing = Promise.all([settingBlockData, unsubscribing]).then(() => {
-                                    this.handleExtrinsicSuccess(resolve, reject, receipt);
-                                });
-                            }
-                            else if (receipt.isError) {
-                                reject(new internal_1.PolymeshError({ code: types_1.ErrorCode.TransactionAborted }));
-                            }
-                            finishing.catch((err) => reject(err));
-                        }
-                    });
-                    gettingUnsub
-                        .then(() => {
-                        // tx approved by signer
-                        this.setIsRunningStatus(txWithArgs.hash.toString());
-                    })
-                        .catch((err) => {
-                        const error = (0, utils_1.handleTransactionSubmissionError)(err);
-                        reject(new internal_1.PolymeshError(error));
-                    });
+                return this.runViaSubscription({
+                    subscribe: callback => txWithArgs.signAndSend(signingAddress, signerOptions, callback),
+                    getTxHash: () => txWithArgs.hash.toString(),
                 });
             }
-            else {
-                return this.runViaPolling(txWithArgs, signerOptions);
-            }
+            return this.runViaPolling(() => Promise.resolve(this.buildNativePollingSubmission(txWithArgs, signerOptions)));
         });
     }
     /**
      * @hidden
      *
-     * Sign and submit the transaction, then poll for its finalization. Used when the
-     *   node connection does not support subscriptions
+     * Compose the transaction and assemble the options the native signer is called with. Also moves
+     *   the transaction into `Unapproved`, since from here on the signer is what everything waits on
      */
-    runViaPolling(txWithArgs, signerOptions) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { signingAddress, context } = this;
-            const startingBlock = yield context.getLatestBlock();
+    buildNativeSignerData() {
+        var _a;
+        const { signer, mortality, context } = this;
+        // era is how many blocks the transaction remains valid for, `undefined` for default
+        const era = mortality.immortal ? 0 : (_a = mortality.lifetime) === null || _a === void 0 ? void 0 : _a.toNumber();
+        const nonce = context.getNonce().toNumber();
+        this.updateStatus(types_1.TransactionStatus.Unapproved);
+        const txWithArgs = this.composeTx();
+        const signerOptions = Object.assign(Object.assign({ nonce, 
             /*
-             * the resolved hash is used instead of `txWithArgs.hash` because a signer may return a modified
-             *   `signedTransaction` (e.g. Ledger devices signing via the generic app), in which case the
-             *   submitted extrinsic's hash can differ from the locally composed one
+             * allows signers (e.g. Ledger devices signing via the generic app) to return a modified
+             *   `signedTransaction`, which is required when signed extensions like `CheckMetadataHash` alter the payload
              */
-            const submittedTxHash = yield txWithArgs
-                .signAndSend(signingAddress, signerOptions)
-                .then(txHash => {
-                this.setIsRunningStatus(txHash.toString());
-                return txHash;
+            withSignedTransaction: true, 
+            /*
+             * a returned `signedTransaction` may only alter signed extensions (e.g. `mode`, `metadataHash`).
+             *   The API will reject any submission where the signer changed the call data itself
+             */
+            allowCallDataAlteration: false }, (signer && { signer })), (era !== undefined ? { era } : {}));
+        return { txWithArgs, signerOptions };
+    }
+    /**
+     * @hidden
+     *
+     * The native "send once and correlate by hash" submission. Used when the connection has no
+     *   subscription support, and by {@link broadcast}, which cannot use the callback-driven
+     *   subscription at all since that never yields control back before the transaction resolves
+     */
+    buildNativePollingSubmission(txWithArgs, signerOptions) {
+        const { signingAddress } = this;
+        return {
+            send: () => __awaiter(this, void 0, void 0, function* () {
+                /*
+                 * the resolved hash is used instead of `txWithArgs.hash` because a signer may return a modified
+                 *   `signedTransaction` (e.g. Ledger devices signing via the generic app), in which case the
+                 *   submitted extrinsic's hash can differ from the locally composed one
+                 */
+                const submittedTxHash = yield txWithArgs.signAndSend(signingAddress, signerOptions);
+                return {
+                    txHash: submittedTxHash.toString(),
+                    matcher: (0, utils_1.extrinsicHashMatcher)(submittedTxHash),
+                };
+            }),
+        };
+    }
+    /**
+     * @hidden
+     *
+     * @throws `ValidationError` if the caller explicitly requested a mortality setting.
+     *   Ethereum transactions have no era; replay protection comes from the nonce and chain id, so
+     *   `ProcedureOpts.mortality` is meaningless on this path and silently ignoring a request for
+     *   immortality that the transport cannot honour would be worse than a clear error
+     */
+    assertMortalitySupportedForEth() {
+        const { mortality } = this;
+        const wasExplicitlySet = mortality.immortal || mortality.lifetime !== undefined;
+        if (wasExplicitlySet) {
+            throw new internal_1.PolymeshError({
+                code: types_1.ErrorCode.ValidationError,
+                message: 'Mortality cannot be set for a transaction signed by an Ethereum key. Ethereum transactions have no era; replay protection comes from the nonce and chain id, so they are effectively immortal until the nonce is consumed',
+            });
+        }
+    }
+    /**
+     * @hidden
+     *
+     * Ethereum submission strategy: build the request (performing the mandatory dry run
+     *   pre-flight), then either broadcast a raw signed transaction from the SDK, or let the
+     *   wallet broadcast and correlate the result by scanning blocks for a matching
+     *   `revive.ethTransact` extrinsic
+     */
+    internalRunEth() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { context } = this;
+            const { ethSigner, request } = yield this.buildEthRequest();
+            const strategy = (0, ethTransaction_1.getEthSubmissionStrategy)(ethSigner);
+            if (strategy.mode === 'sdkBroadcast' && context.supportsSubscription()) {
+                const rawSignedTx = yield strategy.signTransaction(request);
+                const { subscription } = (0, ethTransaction_1.buildSdkBroadcastSubmission)(context, rawSignedTx);
+                return this.runViaSubscription(subscription);
+            }
+            return this.runViaPolling(this.buildEthPollingSubmission(strategy, request));
+        });
+    }
+    /**
+     * @hidden
+     *
+     * The eager half of the Ethereum path: validate, compose the call and perform the mandatory dry
+     *   run pre-flight. Deliberately kept out of the broadcast phase — it is chain RPC work, not a
+     *   signer interaction, so a failure here is a real error rather than something a timeout should
+     *   describe as "state unknown"
+     */
+    buildEthRequest() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { context, signingAddress } = this;
+            this.assertMortalitySupportedForEth();
+            const ethSigner = context.getEthSigner();
+            if (!ethSigner) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.General,
+                    message: 'There is no Ethereum signer associated with the SDK instance. Please report this to the Polymesh team',
+                });
+            }
+            this.updateStatus(types_1.TransactionStatus.Unapproved);
+            const composedTx = this.composeTx();
+            const nonceValue = context.getNonce();
+            const nonceOverride = nonceValue.isNegative() ? undefined : nonceValue;
+            const { request } = yield (0, ethTransaction_1.buildEthTransactionRequest)(Object.assign({ context,
+                signingAddress,
+                composedTx,
+                ethSigner }, (nonceOverride ? { nonce: nonceOverride } : {})));
+            return { ethSigner, request };
+        });
+    }
+    /**
+     * @hidden
+     *
+     * The deferred half of the Ethereum path. Everything that touches the signer lives in here, so
+     *   that the broadcast timeout covers the wallet confirmation prompt in both modes: the raw
+     *   signing in `sdkBroadcast`, and the sign-and-send in `walletBroadcast`
+     */
+    buildEthPollingSubmission(strategy, request) {
+        const { context } = this;
+        if (strategy.mode === 'sdkBroadcast') {
+            const { signTransaction } = strategy;
+            return () => __awaiter(this, void 0, void 0, function* () {
+                const rawSignedTx = yield signTransaction(request);
+                return (0, ethTransaction_1.buildSdkBroadcastSubmission)(context, rawSignedTx).polling;
+            });
+        }
+        /*
+         * The wallet broadcasts and returns the Ethereum transaction hash. The SDK submitted
+         *   nothing, so there is no extrinsic-status subscription to attach to and the result has to
+         *   be located by scanning blocks for the matching `revive.ethTransact` extrinsic
+         */
+        const walletBroadcastSubmission = (0, ethTransaction_1.buildWalletBroadcastSubmission)(strategy.sendTransaction, request);
+        return () => Promise.resolve({
+            send: () => __awaiter(this, void 0, void 0, function* () {
+                const result = yield walletBroadcastSubmission.send();
+                // set as soon as the hash is known, even if the transaction later reverts or is not found
+                this.ethTxHash = result.txHash;
+                return result;
+            }),
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Submit the transaction and track it through a subscription, updating the transaction's
+     *   status and block data as the node reports progress. All lifecycle bookkeeping lives here,
+     *   so the only thing a submission strategy has to provide is *how* the transaction reaches
+     *   the chain
+     */
+    runViaSubscription(submission) {
+        const { subscribe, getTxHash } = submission;
+        return new Promise((resolve, reject) => {
+            let settingBlockData = Promise.resolve();
+            const gettingUnsub = subscribe(receipt => {
+                const { status } = receipt;
+                let isLastCallback = false;
+                let unsubscribing = Promise.resolve();
+                let failureError;
+                if (status.isFuture) {
+                    this.updateStatus(types_1.TransactionStatus.Future);
+                }
+                else if (receipt.isCompleted) {
+                    // isCompleted implies status is one of: isFinalized, isInBlock or isError
+                    if (receipt.isInBlock) {
+                        const inBlockHash = status.asInBlock;
+                        /*
+                         * this must be done to ensure that the block hash and number are set before the success event
+                         *   is emitted, and at the same time. We do not resolve or reject the containing promise until this
+                         *   one resolves
+                         */
+                        settingBlockData = (0, internal_3.defusePromise)(this.context.polymeshApi.rpc.chain.getBlock(inBlockHash).then(({ block }) => {
+                            this.blockHash = (0, conversion_1.hashToString)(inBlockHash);
+                            this.blockNumber = (0, conversion_1.u32ToBigNumber)(block.header.number.unwrap());
+                            // we know that the index has to be set by the time the transaction is included in a block
+                            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                            this.txIndex = new bignumber_js_1.default(receipt.txIndex);
+                            this.updateStatus(types_1.TransactionStatus.InBlock);
+                        }));
+                        // if the extrinsic failed due to an on-chain error, we should handle it in a special way
+                        failureError = this.getReceiptFailure(receipt);
+                        // extrinsic failed so we can unsubscribe
+                        isLastCallback = !!failureError;
+                    }
+                    else {
+                        // isFinalized || isError so we know we can unsubscribe
+                        isLastCallback = true;
+                    }
+                    if (isLastCallback) {
+                        unsubscribing = gettingUnsub.then((unsub) => {
+                            unsub();
+                        });
+                    }
+                    /*
+                     * Promise chain that handles all sub-promises in this pass through the signAndSend callback.
+                     * Primarily for consistent error handling
+                     */
+                    let finishing = Promise.resolve();
+                    if (failureError) {
+                        const error = failureError;
+                        finishing = Promise.all([settingBlockData, unsubscribing]).then(() => {
+                            reject(error);
+                        });
+                    }
+                    else if (receipt.isFinalized) {
+                        finishing = Promise.all([settingBlockData, unsubscribing]).then(() => {
+                            this.handleExtrinsicSuccess(resolve, reject, receipt);
+                        });
+                    }
+                    else if (receipt.isError) {
+                        reject(new internal_1.PolymeshError({ code: types_1.ErrorCode.TransactionAborted }));
+                    }
+                    finishing.catch((err) => reject(err));
+                }
+            });
+            gettingUnsub
+                .then(() => {
+                // tx approved by signer
+                this.setIsRunningStatus(getTxHash());
             })
                 .catch((err) => {
                 const error = (0, utils_1.handleTransactionSubmissionError)(err);
-                throw new internal_1.PolymeshError(error);
+                reject(new internal_1.PolymeshError(error));
             });
-            const finalizedReceipt = yield (0, utils_1.pollForTransactionFinalization)(submittedTxHash, startingBlock, context);
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Submit the transaction, then locate it by scanning the chain's blocks. Used when there is no
+     *   extrinsic status subscription to attach to — either because the connection does not support
+     *   subscriptions, or because the transaction was broadcast by an Ethereum wallet rather than
+     *   by the SDK
+     */
+    runViaPolling(getSubmission) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const startingBlock = yield this.context.getLatestBlock();
+            const { matcher } = yield this.broadcastToChain(getSubmission);
+            return this.watchForInclusion(matcher, startingBlock);
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Hand the transaction to its signer and get it broadcast, yielding the hash it can be looked up
+     *   by and the predicate that recognizes it in a block. This is the phase a wallet confirmation
+     *   prompt happens in, so it is what `submission.broadcastTimeout` bounds
+     *
+     * @throws `TransactionTimeout` if the signer does not broadcast in time. Note this says nothing
+     *   about whether the transaction was broadcast — only that the SDK gave up waiting to hear
+     */
+    broadcastToChain(getSubmission) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { submissionOpts: { broadcastTimeout }, } = this;
+            const sending = (() => __awaiter(this, void 0, void 0, function* () {
+                const submission = yield getSubmission();
+                return submission.send();
+            }))();
+            const result = yield (0, internal_3.withTimeout)(sending, broadcastTimeout, () => new internal_1.PolymeshError({
+                code: types_1.ErrorCode.TransactionTimeout,
+                message: 'The signer did not broadcast the transaction within the allotted time. It was not cancelled — whether it ends up being broadcast is unknown, so check before submitting again, or the same transaction may be submitted twice',
+                data: { broadcastTimeout },
+            })).catch((err) => {
+                /*
+                 * a timeout is already a well formed error describing exactly what happened. Only genuine
+                 *   submission failures need translating (e.g. a signer cancellation)
+                 */
+                if (err instanceof internal_1.PolymeshError && err.code === types_1.ErrorCode.TransactionTimeout) {
+                    throw err;
+                }
+                throw (0, utils_1.handleTransactionSubmissionError)(err);
+            });
+            this.setIsRunningStatus(result.txHash);
+            return result;
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Locate the broadcast transaction by scanning blocks, updating this transaction's block data as
+     *   it goes. Bounded by `submission.watchTimeout`, or by the `timeout` passed to the `watch`
+     *   returned from {@link broadcast}, which takes precedence
+     *
+     * @throws `TransactionTimeout` if the transaction is not found in time. The transaction is
+     *   unaffected by this and may still be included in a block afterwards
+     */
+    watchForInclusion(matcher, startingBlock, timeout) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { context, submissionOpts } = this;
+            const watchTimeout = timeout !== null && timeout !== void 0 ? timeout : submissionOpts.watchTimeout;
+            /*
+             * report inclusion as soon as the transaction lands in a block, rather than leaving the caller
+             *   with no feedback for the whole finalization window. This matters most for an Ethereum
+             *   transaction the wallet broadcast, where block scanning is the only signal
+             *   available
+             */
+            const onInBlock = ({ blockHash, blockNumber, txIndex }) => {
+                this.blockHash = blockHash;
+                this.blockNumber = blockNumber;
+                this.txIndex = new bignumber_js_1.default(txIndex);
+                this.updateStatus(types_1.TransactionStatus.InBlock);
+            };
+            /*
+             * subscribing is strictly better where the connection allows it: blocks arrive as they are
+             *   produced instead of on a poll tick, and it removes a repeating `getHeader`/`getBlock`
+             *   cycle per in-flight transaction. Polling remains the fallback for HTTP connections, which
+             *   is what it was always intended for
+             */
+            const scanning = context.supportsSubscription()
+                ? (0, utils_1.subscribeForTransactionFinalization)(matcher, startingBlock, context, onInBlock)
+                : (0, utils_1.pollForTransactionFinalization)(matcher, startingBlock, context, undefined, onInBlock);
+            const finalizedReceipt = yield (0, internal_3.withTimeout)(scanning, watchTimeout, () => new internal_1.PolymeshError({
+                code: types_1.ErrorCode.TransactionTimeout,
+                message: 'The transaction was broadcast but was not found in a finalized block within the allotted time. It has not been cancelled and may still be included — it can be tracked by hash with `network.watchTransaction`',
+                data: {
+                    txHash: this.txHash,
+                    ethTxHash: this.ethTxHash,
+                    startingBlock,
+                    watchTimeout,
+                },
+            }));
             this.blockHash = (0, conversion_1.hashToString)(finalizedReceipt.status.asFinalized);
             this.blockNumber = (0, conversion_1.u32ToBigNumber)(finalizedReceipt.blockNumber);
             this.txIndex = new bignumber_js_1.default(finalizedReceipt.txIndex);
             // if the extrinsic failed due to an on-chain error, we should handle it in a special way
-            const [extrinsicFailedEvent] = (0, internal_3.filterEventRecords)(finalizedReceipt, 'system', 'ExtrinsicFailed', true);
-            if (extrinsicFailedEvent) {
-                const { data } = extrinsicFailedEvent;
-                const error = (0, utils_1.handleExtrinsicFailure)(data[0]);
-                throw error;
+            const failureError = this.getReceiptFailure(finalizedReceipt);
+            if (failureError) {
+                throw failureError;
             }
             return finalizedReceipt;
         });
     }
+    /**
+     * @hidden
+     *
+     * Inspect a receipt for an on-chain failure, returning the corresponding error if the
+     *   transaction did not succeed. Checks both `system.ExtrinsicFailed` (the native path) and
+     *   `revive.EthExtrinsicRevert` (the Ethereum signing path, where the outer extrinsic reports
+     *   success even when the inner dispatch failed)
+     */
+    getReceiptFailure(receipt) {
+        return (0, utils_1.getExtrinsicFailure)(receipt);
+    }
     /**
      * Subscribe to status changes
      *
@@ -372,19 +754,26 @@ class PolymeshTransactionBase {
      *
      * @note these values might be inaccurate if the transaction is run at a later time. This can be due to a governance vote or other
      *   chain related factors (like modifications to a specific subsidizer relationship or a chain upgrade)
+     * @note for a transaction signed by an Ethereum key, the `gas` component is derived from
+     *   `ethGas * gasPrice / nativeToEthRatio` (a dry run over the `revive` pallet) rather than
+     *   `payment_queryInfo`, and so may differ slightly from the equivalent native call
      */
     getTotalFees() {
         return __awaiter(this, arguments, void 0, function* (asProposal = true) {
-            const { signingAddress } = this;
+            const { signingAddress, context } = this;
             const composedTx = this.composeTxForFees(asProposal);
-            const paymentInfoPromise = composedTx.paymentInfo(signingAddress);
+            const isEthSigner = (0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format);
+            const gasPromise = isEthSigner
+                ? (0, ethTransaction_1.dryRunEthTransaction)(context, signingAddress, composedTx).then(({ rawEthGas, gasPrice }) => (0, ethTransaction_1.calculateEthGasFee)(rawEthGas, gasPrice, (0, ethTransaction_1.getNativeToEthRatio)(context)))
+                : composedTx
+                    .paymentInfo(signingAddress)
+                    .then(({ partialFee }) => (0, conversion_1.balanceToBigNumber)(partialFee));
             const protocol = yield this.getProtocolFees();
             const payingAccount = yield this.getPayingAccount(asProposal);
-            const [{ partialFee }, { free: balance }] = yield Promise.all([
-                paymentInfoPromise,
+            const [gas, { free: balance }] = yield Promise.all([
+                gasPromise,
                 payingAccount.account.getBalance(),
             ]);
-            const gas = (0, conversion_1.balanceToBigNumber)(partialFee);
             return {
                 fees: {
                     protocol,
@@ -601,6 +990,13 @@ class PolymeshTransactionBase {
         return __awaiter(this, arguments, void 0, function* (metadata = {}, asProposal = true) {
             var _a, _b, _c, _d;
             const { mortality, signingAddress, context, context: { polymeshApi }, } = this;
+            if ((0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format)) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.NotSupported,
+                    message: 'A SCALE `SignerPayload` cannot be produced for a transaction signed by an Ethereum key, since an Ethereum key cannot sign it. Use `toEthSignablePayload` instead',
+                    data: { signingAddress },
+                });
+            }
             const tx = this.composeTxForFees(asProposal);
             const [tipHash, latestBlockNumber] = yield Promise.all([
                 polymeshApi.rpc.chain.getFinalizedHead(),
@@ -646,6 +1042,47 @@ class PolymeshTransactionBase {
             };
         });
     }
+    /**
+     * Returns a representation intended for offline/detached signing of a transaction signed by an
+     *   Ethereum-derived Account. Unlocks Fireblocks / KMS / HSM / air-gapped custody flows: the
+     *   caller signs the returned `transaction` and submits the raw signed bytes via
+     *   {@link api/client/Network!Network.submitEthTransaction | sdk.network.submitEthTransaction}
+     *
+     * @param metadata - Additional information attached to the payload, such as IDs or memos about the transaction
+     * @param opts.eip1559 - whether to build an EIP-1559 (type 2) transaction. Defaults to `true`;
+     *   pass `false` for a custody service or hardware signer that can only encode legacy (type 0)
+     *   transactions
+     *
+     * @note no Signing Manager is required. The whole point of this method is detached signing, so
+     *   it must work on an SDK instance connected without one — the payload is built entirely from
+     *   chain state and the signing address
+     * @note every field of `transaction` is 0x-prefixed hex, never a number or bigint — the only
+     *   encoding that survives being serialized and sent to a remote signer. ethers and viem both
+     *   need it converted first; `@polymeshassociation/eth-signing-manager` exports
+     *   `toEthersTransaction` / `toViemTransaction` for that, usable without the manager itself
+     *
+     * @throws `ValidationError` if the signing Account is not Ethereum-derived
+     */
+    toEthSignablePayload() {
+        return __awaiter(this, arguments, void 0, function* (metadata = {}, opts = {}) {
+            const { signingAddress, context } = this;
+            const { eip1559 = true } = opts;
+            if (!(0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format)) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.ValidationError,
+                    message: '`toEthSignablePayload` can only be used for a transaction signed by an Ethereum-derived Account. Use `toSignablePayload` instead',
+                    data: { signingAddress },
+                });
+            }
+            const composedTx = this.composeTxForFees(true);
+            const nonceValue = context.getNonce();
+            const nonceOverride = nonceValue.isNegative() ? undefined : nonceValue;
+            const transaction = yield (0, ethTransaction_1.buildDetachedEthTransactionRequest)(context, signingAddress, composedTx, eip1559, nonceOverride);
+            const tag = (0, conversion_1.transactionHexToTxTag)(transaction.data, context);
+            const args = context.getTransactionArguments({ tag });
+            return { transaction, tag, args, metadata };
+        });
+    }
     /**
      * returns true if transaction has completed successfully
      */
@@ -667,15 +1104,24 @@ class PolymeshTransactionBase {
      */
     getPayingAccount(asProposal) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { paidForBy, multiSig, context } = this;
-            if (paidForBy) {
+            const { paidForBy, multiSig, context, signingAddress } = this;
+            const isEthSigner = (0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format);
+            /*
+             * An Ethereum-derived Account always pays its own fees. `revive.ethTransact` is a bare
+             *   extrinsic, so neither `paidForBy` nor a subsidy reaches the chain's fee pipeline — gas is
+             *   charged to the signing Account.
+             *
+             * Both branches below would need revisiting if the chain ever routes third-party payment
+             *   through this transport
+             */
+            if (paidForBy && !isEthSigner) {
                 const { account: primaryAccount } = yield paidForBy.getPrimaryAccount();
                 return {
                     type: types_1.PayingAccountType.Other,
                     account: primaryAccount,
                 };
             }
-            const subsidyWithAllowance = yield context.accountSubsidy();
+            const subsidyWithAllowance = isEthSigner ? null : yield context.accountSubsidy();
             if (subsidyWithAllowance && !this.ignoresSubsidy()) {
                 const { subsidy: { subsidizer: account }, allowance, } = subsidyWithAllowance;
                 return {
@@ -723,8 +1169,20 @@ class PolymeshTransactionBase {
      * Wrap a transaction with a multiSig proposal if the signer is a multiSig signer
      */
     wrapProposalIfNeeded(tx) {
-        const { context, context: { polymeshApi: { tx: { multiSig }, }, }, multiSig: actingMultiSig, multiSigOpts, } = this;
+        const { context, context: { polymeshApi: { tx: { multiSig }, }, }, multiSig: actingMultiSig, multiSigOpts, signingAddress, } = this;
         if (actingMultiSig) {
+            /*
+             * MultiSig + Ethereum is a narrow, untested intersection: `getPayingAccount` resolves fees
+             *   to a *native* primary key for a MultiSig proposal, while the gas-derived fee arithmetic
+             *   describes the transaction the Ethereum key itself submits. Out of scope for now,
+             *   rather than shipping an untested combination of two fee models
+             */
+            if ((0, eth_1.isEthDerivedAddress)(signingAddress, context.ss58Format)) {
+                throw new internal_1.PolymeshError({
+                    code: types_1.ErrorCode.NotSupported,
+                    message: 'Using an Ethereum-derived Account as a MultiSig signer is not currently supported',
+                });
+            }
             const rawMultiSigId = (0, conversion_1.stringToAccountId)(actingMultiSig.address, context);
             const rawExpiry = (0, internal_3.optionize)(conversion_1.dateToMoment)(multiSigOpts.expiry, context);
             return multiSig.createProposal(rawMultiSigId, tx, rawExpiry);