@trustvc/trustvc 2.10.0 → 2.11.0

package/README.md

@@ -27,6 +27,7 @@ TrustVC is a comprehensive wrapper library designed to simplify the signing and
       - [b) Token Registry V5](#b-token-registry-v5)
     - [8. **Document Builder**](#8-document-builder)
     - [9. **Document Store**](#9-document-store)
+    - [10. **Transaction Cancel**](#10-transaction-cancel)
 
 ## Installation
 
@@ -1107,3 +1108,56 @@ for (const hash of documentHashes) {
   await documentStoreIssue(storeAddress, hash, signer);
 }
 ```
+
+---
+
+## 10. Transaction Cancel
+
+TrustVC provides a utility to cancel a pending Ethereum transaction by replacing it with a 0-value transaction to the same address, using the same nonce and a higher gas price (replace-by-fee). This works with both ethers v5 and v6 signers.
+
+**Reference:** [How to cancel Ethereum pending transactions](https://info.etherscan.com/how-to-cancel-ethereum-pending-transactions/)
+
+### cancelTransaction
+
+#### Description
+
+Cancels a pending transaction by sending a 0-value transaction to the signer’s address with the same nonce and a higher gas price. You can specify the pending transaction either by **transaction hash** (nonce and gas price are fetched; gas price is doubled) or by **nonce and gas price** explicitly. Transactions that use EIP-1559 (no legacy `gasPrice`) must be cancelled using nonce and gas price.
+
+#### Parameters
+
+- **signer** – Signer with a connected provider; type `CancelTransactionSigner` (compatible with ethers v5 and v6 signers).
+- **options** – `CancelTransactionOptions`:
+  - **transactionHash** (optional): Pending transaction hash (`0x...`). If provided, nonce and gas price are read from the chain and gas price is increased by 100%.
+  - **nonce** (optional): Pending transaction nonce. Must be used together with `gasPrice`.
+  - **gasPrice** (optional): Gas price in wei for the replacement transaction. Must be used together with `nonce`.
+
+Either `(nonce, gasPrice)` or `transactionHash` must be provided.
+
+#### Returns
+
+**Promise<string>** – The replacement transaction hash.
+
+#### Throws
+
+- If the signer has no provider.
+- If neither `(nonce, gasPrice)` nor `transactionHash` is provided.
+- If `transactionHash` is given but the transaction is not found.
+- If the transaction uses EIP-1559 (no `gasPrice`); in that case use nonce and gas price explicitly.
+
+#### Example
+
+```ts
+import { cancelTransaction } from '@trustvc/trustvc';
+
+// Cancel by transaction hash (gas price is fetched and doubled)
+const replacementHash = await cancelTransaction(signer, {
+  transactionHash: '0x...',
+});
+console.log('Replacement tx:', replacementHash);
+
+// Or cancel by nonce and gas price (e.g. for EIP-1559 txs)
+const replacementHash2 = await cancelTransaction(signer, {
+  nonce: '5',
+  gasPrice: '25000000000', // 25 gwei in wei
+});
+```

package/dist/cjs/index.js

@@ -3,6 +3,7 @@
 var tokenRegistryV4 = require('./token-registry-v4');
 var tokenRegistryV5 = require('./token-registry-v5');
 var documentStore = require('./document-store');
+var transaction = require('./transaction');
 var tokenRegistryFunctions = require('./token-registry-functions');
 var core = require('./core');
 var openAttestation = require('./open-attestation');
@@ -118,6 +119,16 @@ Object.defineProperty(exports, "getRoleString", {
   enumerable: true,
   get: function () { return documentStore.getRoleString; }
 });
+Object.defineProperty(exports, "cancelTransaction", {
+  enumerable: true,
+  get: function () { return transaction.cancelTransaction; }
+});
+Object.keys(transaction).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return transaction[k]; }
+  });
+});
 Object.keys(tokenRegistryFunctions).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
     enumerable: true,

package/dist/cjs/transaction/cancel.js

@@ -0,0 +1,57 @@
+'use strict';
+
+var ethers = require('ethers');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const GAS_PRICE_SCALE_WHEN_FROM_HASH = 2;
+const cancelTransaction = /* @__PURE__ */ __name(async (signer, options) => {
+  if (!signer.provider) {
+    throw new Error("Provider is required on signer");
+  }
+  const { nonce, gasPrice, transactionHash } = options;
+  let transactionNonce = nonce;
+  let transactionGasPrice = gasPrice;
+  if (transactionHash) {
+    if (typeof signer.provider.getTransaction !== "function") {
+      throw new Error("Provider does not support getTransaction");
+    }
+    const tx = await signer.provider.getTransaction(transactionHash);
+    if (!tx) {
+      throw new Error(`Transaction not found: ${transactionHash}`);
+    }
+    const txNonce = tx.nonce;
+    const txGasPrice = tx.gasPrice;
+    if (txGasPrice == null) {
+      throw new Error(
+        "Transaction uses EIP-1559 (no gasPrice). Cancel by providing --nonce and --gas-price explicitly."
+      );
+    }
+    transactionNonce = String(txNonce);
+    const scaled = typeof txGasPrice === "bigint" ? txGasPrice * BigInt(GAS_PRICE_SCALE_WHEN_FROM_HASH) : ethers.BigNumber.from(txGasPrice).mul(GAS_PRICE_SCALE_WHEN_FROM_HASH);
+    transactionGasPrice = String(scaled);
+  }
+  if (!transactionNonce || !transactionGasPrice) {
+    throw new Error(
+      "Provide either (--nonce and --gas-price) or --transaction-hash to cancel the pending transaction"
+    );
+  }
+  const address = await signer.getAddress();
+  if (!/^\d+$/.test(transactionNonce)) {
+    throw new Error("Invalid nonce: expected a non-negative integer");
+  }
+  if (!/^\d+$/.test(transactionGasPrice) || transactionGasPrice === "0") {
+    throw new Error("Invalid gasPrice: expected a positive integer string in wei");
+  }
+  const nonceNum = Number(transactionNonce);
+  const txResponse = await signer.sendTransaction({
+    to: address,
+    value: 0,
+    nonce: nonceNum,
+    gasPrice: transactionGasPrice,
+    gasLimit: 21e3
+  });
+  return txResponse.hash;
+}, "cancelTransaction");
+
+exports.cancelTransaction = cancelTransaction;

package/dist/cjs/transaction/index.js

@@ -0,0 +1,10 @@
+'use strict';
+
+var cancel = require('./cancel');
+
+
+
+Object.defineProperty(exports, "cancelTransaction", {
+  enumerable: true,
+  get: function () { return cancel.cancelTransaction; }
+});

package/dist/esm/index.js

@@ -1,6 +1,8 @@
 export { v4ComputeInterfaceId, v4ComputeTitleEscrowAddress, v4ContractAddress, v4Contracts, v4EncodeInitParams, v4GetEventFromReceipt, v4RoleHash, v4SupportInterfaceIds, v4Utils } from './token-registry-v4';
 export { v5ComputeInterfaceId, v5ContractAddress, v5Contracts, v5EncodeInitParams, v5GetEventFromReceipt, v5RoleHash, v5SupportInterfaceIds, v5Utils } from './token-registry-v5';
 export { DocumentStore__factory, TransferableDocumentStore__factory, deployDocumentStore, documentStoreGrantRole, documentStoreIssue, documentStoreRevoke, documentStoreRevokeRole, documentStoreTransferOwnership, getRoleString } from './document-store';
+export * from './transaction';
+export { cancelTransaction } from './transaction';
 export * from './token-registry-functions';
 export * from './core';
 export * from './open-attestation';

package/dist/esm/transaction/cancel.js

@@ -0,0 +1,55 @@
+import { BigNumber } from 'ethers';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const GAS_PRICE_SCALE_WHEN_FROM_HASH = 2;
+const cancelTransaction = /* @__PURE__ */ __name(async (signer, options) => {
+  if (!signer.provider) {
+    throw new Error("Provider is required on signer");
+  }
+  const { nonce, gasPrice, transactionHash } = options;
+  let transactionNonce = nonce;
+  let transactionGasPrice = gasPrice;
+  if (transactionHash) {
+    if (typeof signer.provider.getTransaction !== "function") {
+      throw new Error("Provider does not support getTransaction");
+    }
+    const tx = await signer.provider.getTransaction(transactionHash);
+    if (!tx) {
+      throw new Error(`Transaction not found: ${transactionHash}`);
+    }
+    const txNonce = tx.nonce;
+    const txGasPrice = tx.gasPrice;
+    if (txGasPrice == null) {
+      throw new Error(
+        "Transaction uses EIP-1559 (no gasPrice). Cancel by providing --nonce and --gas-price explicitly."
+      );
+    }
+    transactionNonce = String(txNonce);
+    const scaled = typeof txGasPrice === "bigint" ? txGasPrice * BigInt(GAS_PRICE_SCALE_WHEN_FROM_HASH) : BigNumber.from(txGasPrice).mul(GAS_PRICE_SCALE_WHEN_FROM_HASH);
+    transactionGasPrice = String(scaled);
+  }
+  if (!transactionNonce || !transactionGasPrice) {
+    throw new Error(
+      "Provide either (--nonce and --gas-price) or --transaction-hash to cancel the pending transaction"
+    );
+  }
+  const address = await signer.getAddress();
+  if (!/^\d+$/.test(transactionNonce)) {
+    throw new Error("Invalid nonce: expected a non-negative integer");
+  }
+  if (!/^\d+$/.test(transactionGasPrice) || transactionGasPrice === "0") {
+    throw new Error("Invalid gasPrice: expected a positive integer string in wei");
+  }
+  const nonceNum = Number(transactionNonce);
+  const txResponse = await signer.sendTransaction({
+    to: address,
+    value: 0,
+    nonce: nonceNum,
+    gasPrice: transactionGasPrice,
+    gasLimit: 21e3
+  });
+  return txResponse.hash;
+}, "cancelTransaction");
+
+export { cancelTransaction };

package/dist/esm/transaction/index.js

@@ -0,0 +1 @@
+export { cancelTransaction } from './cancel';

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@ export { documentStoreTransferOwnership } from './document-store/transferOwnersh
 export { deployDocumentStore } from './deploy/document-store.js';
 export { getRoleString } from './document-store/document-store-roles.js';
 export { DocumentStore__factory, TransferableDocumentStore__factory } from '@trustvc/document-store';
+export { CancelTransactionOptions, CancelTransactionSigner, cancelTransaction } from './transaction/cancel.js';
 export { nominate, transferBeneficiary, transferHolder, transferOwners } from './token-registry-functions/transfer.js';
 export { rejectTransferBeneficiary, rejectTransferHolder, rejectTransferOwners } from './token-registry-functions/rejectTransfers.js';
 export { acceptReturned, rejectReturned, returnToIssuer } from './token-registry-functions/returnToken.js';

package/dist/types/transaction/cancel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Transaction Cancel Module
+ *
+ * Cancels a pending transaction by replacing it with a 0-value transaction to self
+ * using the same nonce and a higher gas price (e.g. 2x when using --transaction-hash).
+ * @see https://info.etherscan.com/how-to-cancel-ethereum-pending-transactions/
+ */
+interface CancelTransactionOptions {
+    /** Pending transaction nonce (use with gasPrice, or use transactionHash instead) */
+    nonce?: string;
+    /** Gas price higher than the pending transaction (use with nonce) */
+    gasPrice?: string;
+    /** Pending transaction hash; nonce and gas price will be fetched and gas price increased by 100% */
+    transactionHash?: string;
+}
+/** Signer with provider, compatible with ethers v5 and v6. */
+interface CancelTransactionSigner {
+    getAddress(): Promise<string>;
+    provider: {
+        getTransaction?(hash: string): Promise<unknown>;
+    } | null;
+    sendTransaction(tx: Record<string, unknown>): Promise<{
+        hash: string;
+    }>;
+}
+/**
+ * Cancels a pending transaction by sending a 0-value transaction to self with the same nonce
+ * and a higher gas price. Supports both ethers v5 and v6 signers via a unified transaction object.
+ * @param {CancelTransactionSigner} signer - Signer with provider (ethers v5 or v6)
+ * @param {CancelTransactionOptions} options - Either (nonce + gasPrice) or transactionHash
+ * @returns {Promise<string>} The replacement transaction hash
+ * @throws If neither (nonce and gasPrice) nor transactionHash is provided
+ * @throws If provider is not available on signer
+ */
+declare const cancelTransaction: (signer: CancelTransactionSigner, options: CancelTransactionOptions) => Promise<string>;
+
+export { type CancelTransactionOptions, type CancelTransactionSigner, cancelTransaction };

package/dist/types/transaction/index.d.ts

@@ -0,0 +1 @@
+export { CancelTransactionOptions, CancelTransactionSigner, cancelTransaction } from './cancel.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trustvc/trustvc",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "TrustVC library",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",