@trustvc/trustvc 2.10.0 → 2.11.1

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/open-attestation/utils.js

@@ -21,24 +21,15 @@ const ENCRYPTION_PARAMETERS = Object.freeze({
   // Type 1 using the above params without compression
 });
 const generateEncryptionKey = /* @__PURE__ */ __name((keyLengthInBits = ENCRYPTION_PARAMETERS.keyLength) => {
-  if (!Number.isInteger(keyLengthInBits) || ![128, 192, 256].includes(keyLengthInBits)) {
-    throw new Error("keyLengthInBits must be one of 128, 192, or 256");
-  }
   const encryptionKey = forge__default.default.random.getBytesSync(keyLengthInBits / 8);
   return forge__default.default.util.bytesToHex(encryptionKey);
 }, "generateEncryptionKey");
 const encodeDocument = /* @__PURE__ */ __name((document) => {
   const bytes = forge__default.default.util.encodeUtf8(document);
-  const standard = forge__default.default.util.encode64(bytes);
-  const s = standard.replace(/\+/g, "-").replace(/\//g, "_");
-  const trim = s.endsWith("==") ? 2 : s.endsWith("=") ? 1 : 0;
-  return trim ? s.slice(0, -trim) : s;
+  return forge__default.default.util.encode64(bytes);
 }, "encodeDocument");
 const decodeDocument = /* @__PURE__ */ __name((encoded) => {
-  let normalized = encoded.replace(/-/g, "+").replace(/_/g, "/");
-  const pad = normalized.length % 4;
-  if (pad) normalized += "=".repeat(4 - pad);
-  const decoded = forge__default.default.util.decode64(normalized);
+  const decoded = forge__default.default.util.decode64(encoded);
   return forge__default.default.util.decodeUtf8(decoded);
 }, "decodeDocument");
 const {

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/open-attestation/utils.js

@@ -16,24 +16,15 @@ const ENCRYPTION_PARAMETERS = Object.freeze({
   // Type 1 using the above params without compression
 });
 const generateEncryptionKey = /* @__PURE__ */ __name((keyLengthInBits = ENCRYPTION_PARAMETERS.keyLength) => {
-  if (!Number.isInteger(keyLengthInBits) || ![128, 192, 256].includes(keyLengthInBits)) {
-    throw new Error("keyLengthInBits must be one of 128, 192, or 256");
-  }
   const encryptionKey = forge.random.getBytesSync(keyLengthInBits / 8);
   return forge.util.bytesToHex(encryptionKey);
 }, "generateEncryptionKey");
 const encodeDocument = /* @__PURE__ */ __name((document) => {
   const bytes = forge.util.encodeUtf8(document);
-  const standard = forge.util.encode64(bytes);
-  const s = standard.replace(/\+/g, "-").replace(/\//g, "_");
-  const trim = s.endsWith("==") ? 2 : s.endsWith("=") ? 1 : 0;
-  return trim ? s.slice(0, -trim) : s;
+  return forge.util.encode64(bytes);
 }, "encodeDocument");
 const decodeDocument = /* @__PURE__ */ __name((encoded) => {
-  let normalized = encoded.replace(/-/g, "+").replace(/_/g, "/");
-  const pad = normalized.length % 4;
-  if (pad) normalized += "=".repeat(4 - pad);
-  const decoded = forge.util.decode64(normalized);
+  const decoded = forge.util.decode64(encoded);
   return forge.util.decodeUtf8(decoded);
 }, "decodeDocument");
 const {

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/open-attestation/encrypt.d.ts

@@ -3,10 +3,10 @@ import '@tradetrust-tt/tradetrust';
 import '@tradetrust-tt/tradetrust/dist/types/shared/utils';
 
 /**
- * Encrypts a given string with symmetric AES-GCM.
- * @param {string} document - Input string to encrypt.
- * @param {string} [key] - Optional encryption key in hexadecimal (64 chars for 256-bit). If omitted, a key is generated.
- * @returns {IEncryptionResults} Object with cipherText (base64), iv (base64), tag (base64), key (hex), and type.
+ * Encrypts a given string with symmetric AES
+ * @param {string} document Input string to encrypt
+ * @param {string} [key] Optional encryption key in hexadecimal; generated if omitted
+ * @returns {IEncryptionResults} Object with cipherText (base64), iv (base64), tag (base64), key (hex), and type (algorithm identifier)
  */
 declare const encryptString: (document: string, key?: string) => IEncryptionResults;
 

package/dist/types/open-attestation/utils.d.ts

@@ -19,23 +19,21 @@ declare const ENCRYPTION_PARAMETERS: Readonly<{
     readonly version: "OPEN-ATTESTATION-TYPE-1";
 }>;
 /**
- * Generates a random key represented as a hexadecimal string.
- * @param {number} [keyLengthInBits] - Key length in bits.
- * @returns {string} Hexadecimal-encoded encryption key.
+ * Generates a random key represented as a hexadecimal string
+ * @param {number} keyLengthInBits Key length in bits
+ * @returns {string} Encryption key as hexadecimal string
  */
-declare const generateEncryptionKey: (keyLengthInBits?: number) => string;
+declare const generateEncryptionKey: (keyLengthInBits?: 256) => string;
 /**
- * Encode document string to URL-safe base64 (base64url: UTF-8 then base64 with +→-, /→_, no padding).
- * Safe for use in query strings and JSON without further encoding.
- * @param {string} document - Plain text document to encode.
- * @returns {string} Base64url-encoded string.
+ * Encode document string to base64 (UTF-8 then base64).
+ * @param {string} document UTF-8 document string to encode
+ * @returns {string} Base64-encoded document
  */
 declare const encodeDocument: (document: string) => string;
 /**
- * Decode base64url-encoded document string back to UTF-8.
- * Accepts both base64url (no padding, - and _) and standard base64 for backwards compatibility.
- * @param {string} encoded - Base64- or base64url-encoded string to decode.
- * @returns {string} Decoded UTF-8 plain text.
+ * Decode base64-encoded document string back to UTF-8.
+ * @param {string} encoded Base64-encoded document string
+ * @returns {string} Decoded UTF-8 document string
  */
 declare const decodeDocument: (encoded: string) => string;
 declare const isTransferableAsset: (document: any) => boolean;

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.1",
   "description": "TrustVC library",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",