@btq-js/tx

This package is based on EthereumJS's Tx package. Most of the implementation and interfaces remains the same, except that:

1. For signature scheme, we replaced ECDSA with Falcon for quantum safety.
2. Transation structure remains the same. However, definitions for r, s and v are changed due to new signature scheme. Please see the definition in the table describing txData.
3. In TxOptions we add a new option publicKey due to the design that Falcon public key can not be recovered from its signature. For more detail please take a look at TxOptions section.

We strongly suggest to read through the documentations from EthereumJS's Tx package beforehead.

Please note that:

This package depends on @btq-js/falcon-js by default. If we want to change the underlying falcon implementation from javascript to web assembly, please follw these simple steps

Installation

To obtain the latest version, simply require the project using npm:

npm install @btq-js/tx

You can also use yarn or pnpm based on your project's setup:

yarn add @btq-js/tx

pnpm add @btq-js/tx

Transaction Types

Currently the following transaction types are supported

| Name | Description | | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | FeeMarketEIP1559Transaction | EIP-1559, gas fee market | | AccessListEIP2930Transaction | EIP-2930, optional access lists | | Legacy Transaction | Legacy or type-0 transactions |

Gas Fee Market Transactions (EIP-1559)

| Name | Value | | ----------- | --------------------------------------------------------------- | | Class | FeeMarketEIP1559Transaction | | Type | 2 | | txData type | FeeMarketEIP1559TxData |

import { FeeMarketEIP1559Transaction } from '@btq-js/tx';

const txData = {
  type: 2,
  nonce: 0,
  maxPriorityFeePerGas: 100,
  maxFeePerGas: 1000,
  gasLimit: 1000000000,
  value: 0,
  to: '0x8dDDbD32233CfAA36aa659feebFCD4368DF8c18f',
};
const tx = FeeMarketEIP1559Transaction.fromTxData(txData);

Access List Transactions (EIP-2930)

| Name | Value | | ----------- | ----------------------------------------------------------------- | | Class | AccessListEIP2930Transaction | | Type | 1 | | txData type | AccessListEIP2930TxData |

import { AccessListEIP2930Transaction } from '@btq-js/tx';

const txData = {
  type: 1,
  nonce: 1,
  gasPrice: 100,
  gasLimit: 1000000000,
  value: 0,
  to: '0x8dDDbD32233CfAA36aa659feebFCD4368DF8c18f',
  chainId: '0x01',
  accessList: [
    {
      address: '0x0000000000000000000000000000000000000101',
      storageKeys: ['0x0000000000000000000000000000000000000000000000000000000000000000', '0x00000000000000000000000000000000000000000000000000000000000060a7'],
    },
  ],
};
const tx = AccessListEIP2930Transaction.fromTxData(txData);

Legacy Transactions

| Name | Value | | ----------- | ------------------------------------------------- | | Class | Transaction | | Type | 0 (internal) | | txData type | txData |

import { Transaction } from '@btq-js/tx';

const txParams = {
  nonce: 1,
  gasPrice: 100,
  gasLimit: 1000000000,
  value: 0,
  to: '0x8dDDbD32233CfAA36aa659feebFCD4368DF8c18f',
  data: '0x1a8451e600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
};

const tx = Transaction.fromTxData(txParams);

Transaction Factory

If you only know on runtime which tx type will be used within your code or if you want to keep your code transparent to tx types, this library comes with a TransactionFactory for your convenience which can be used as follows:

import { TransactionFactory } from '@btq-js/tx';

const txData = {}; // Use data from the different tx type examples
const tx = TransactionFactory.fromTxData(txData);
if (tx.supports(Capability.EIP2930AccessLists)) {
  // Do something which only makes sense for txs with support for access lists
}

The correct tx type class for instantiation will then be chosen on runtime based on the data provided as an input.

TransactionFactory supports the following static constructor methods except for fromEthersProvider() provided by @ethereumjs/tx:

• public static fromTxData(txData: TxData | AccessListEIP2930TxData, txOptions: TxOptions = {}): TypedTransaction
• public static fromSerializedData(data: Buffer, txOptions: TxOptions = {}): TypedTransaction
• public static fromBlockBodyData(data: Buffer | Buffer[], txOptions: TxOptions = {})

Tx signing

import falcon from '@btq-js/falcon-js';

const seed = Buffer.from('<random_seed>', 'hex');

const key = await falcon.keyPair(seed);

const signedTx = await tx.sign(Buffer.from(key.publicKey), Buffer.from(key.privateKey));

Tx serialization

const serializedTx = signedTx.serialize().toString('hex');

const requestData = {
  jsonrpc: '2.0',
  method: 'eth_sendRawTransaction',
  params: [serializedTx],
  id: 1,
};

const postTx = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData),
};

await fetch(network, postData);

TxOptions

We add a new option publicKey which does not exist in EthereumJS's Tx package

| Name | Type | | ------------ | --------- | | common? | Common | | freeze? | boolean | | publicKey? | Buffer |

Unlike ECDSA, Falcon public can not be recovered from its signature, if you want to verify a signed tx which has nonce larger than 0 (its r value is address instead of publicKey), you should provide publicKey.

Please see the following example:

import falcon from '@btq-js/falcon-js';
import { Transaction } from '@btq-js/tx';

const seed = Buffer.from('<random_seed>', 'hex');
const key = await falcon.keyPair(seed);
const publicKey = Buffer.from(key.publicKey);

const txData = {
  nonce: 1,
  gasPrice: 100,
  gasLimit: 1000000000,
  value: 0,
  to: '0x8dDDbD32233CfAA36aa659feebFCD4368DF8c18f',
  data: '0x1a8451e600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
  r: '<address>',
  s: '<signature_generated_by_falcon>',
  v: '<chainId_and_metadata>',
};

const signedTx = Transaction.fromTxData(txData, { publicKey });
// Verification will fail if publicKey is not provided.
const isVerified = await signedTx.verifySignature();