🚀 @txfusion/txsync-sdk

📌 Overview

txsync-sdk abstracts the functionalities of the txSync products and makes it easier to integrate in your project.

We currently support Tsuko, but we're planning to integrate all txSync functionalities. The main power of txsync-sdk lies in the paymaster object and its methods.

• getPaymaster - a function which provides a way to get the Paymaster you created and then call methods on it
• sendPaymasterTransaction - method that populates and sends a transaction using the Paymaster and provided parameters
• populatePaymasterTransaction - method that returns the populated TransactionRequest object, giving you the option to perform additional checks or operations on the transaction data

🛠 Prerequisites

• node: >= 18 (installation guide)
• ethers: ^6.8.0

📥 Installation & Setup

npm install @txfusion/txsync-sdk
// or
yarn add @txfusion/txsync-sdk

🧑‍🍳 Examples

The complete examples with various use cases are available here.

📝 SDK API

getPaymaster

async function getPaymaster(address: Address, runner: Signer | Wallet): Promise<Paymaster>

Creates a new instance of the Paymaster class based on the provided Paymaster contract address.

• address: Address: The address of the Paymaster contract.
• runner: Signer | Wallet: A Signer or Wallet instance for signing and sending transactions.
• Returns: A new Paymaster instance.

Paymaster

The Paymaster class is a utility class that provides methods for interacting with Paymaster contracts on the zkSync network. It supports two types of Paymasters: ERC20Paymaster and SponsoredPaymaster.

Constructor

constructor(address: Address, runner: Signer | Wallet, paymasterType: PaymasterType, chainId: string, token?: Address)

• address: Address - The address of the Paymaster contract.
• runner: Signer | Wallet - A Signer or Wallet instance for signing transactions.
• paymasterType: PaymasterType - type of Paymaster (ERC20Paymaster or SponsoredPaymaster).
• chainId: string - The ID of the chain the Paymaster contract is deployed on.
• token: Address (optional) - The address of the ERC20 token used by the ERC20Paymaster.

populatePaymasterTransaction

async populatePaymasterTransaction(contractAddress: Address, functionToCall: InterfaceAbi, args?: any[], overrides?: PaymasterOverrides): Promise<TransactionRequest>

Populates a TransactionRequest object with the necessary data to call a function on a contract using the Paymaster.

• contractAddress: Address - The address of the contract to call.
• functionToCall: ethers.InterfaceAbi - The definition of the function to call. Can be:
  • Human-Readable fragment - string which resembles a Solidity signature and is introduced in this blog entry. For example, function balanceOf(address) view returns (uint).
  • Parsed JSON fragment - [[Fragment]] instances - JavaScript Object desribed in the Solidity documentation.
• args: any[] (optional) - An array of arguments for the function call.
• overrides: PaymasterOverrides (optional)- An object containing overrides for the transaction (e.g., to, value, data, customData, gasLimit, maxFeePerGas, maxPriorityFeePerGas)
• Returns: A TransactionRequest object populated with the transaction data.

getPaymasterCustomData

getPaymasterCustomData(paymasterOptions?: PaymasterOptions): PaymasterParams

Generates the PaymasterParams object that will be passed to the transaction that's using paymaster.

• paymasterOptions: PaymasterOptions (optional) - An object containing options for the Paymaster (e.g., innerInput, minimalAllowance).
• Returns: A PaymasterParams object.

sendPaymasterTransaction

async sendPaymasterTransaction(contractAddress: Address, functionToCall: InterfaceAbi, args: any[] = [], overrides?: PaymasterOverrides): Promise<TransactionResponse>

Populates and sends a transaction using the Paymaster.

• contractAddress: Address - The address of the contract to call.
• functionToCall: ethers.InterfaceAbi - The definition of the function to call. Can be:
  • Human-Readable fragment - string which resembles a Solidity signature and is introduced in this blog entry. For example, function balanceOf(address) view returns (uint).
  • Parsed JSON fragment - [[Fragment]] instances - JavaScript Object desribed in the Solidity documentation.
• args: any[] (optional) - An array of arguments for the function call.
• overrides: PaymasterOverrides (optional)- An object containing overrides for the transaction (e.g., to, value, data, customData, gasLimit, maxFeePerGas, maxPriorityFeePerGas)
• Returns: A TransactionResponse object.

sendTransaction

async sendTransaction(tx: TransactionRequest): Promise<TransactionResponse>

Sends a populated TransactionRequest object using the Paymaster.

• tx: The TransactionRequest object to send.
• Returns: A TransactionResponse object.

getBalance

async getBalance(): Promise<BigNumberish>

Gets the balance of the Paymaster contract.

• Returns: The balance of the Paymaster contract as a BigNumberish value.

estimateGas

async estimateGas(tx: TransactionRequest): Promise<BigNumberish>

Estimates the gas required for a transaction. Especially tailored for Paymaster paymaster needs.

• tx: The TransactionRequest object for which to estimate the gas.
• Returns: The estimated gas limit as a BigNumberish value.

getPaymasterContract

getPaymasterContract(): ERC20Paymaster | SponsoredPaymaster

Gets an instance of the ERC20Paymaster or SponsoredPaymaster contract, depending on the paymasterType.

• Returns: An instance of the (ethers.Contract).

addRestriction

async addRestriction(address: Address): Promise<ContractTransactionResponse>

Adds a restriction to the Paymaster.

• address: Address - The address of the restriction contract to add.
• Returns: A ContractTransactionResponse object.

getRestrictions

async getRestrictions(): Promise<string[]>

Gets the list of restriction contract addresses added to the Paymaster.

• Returns: An array of restriction contract addresses.

removeRestriction

async removeRestriction(address: Address): Promise<ContractTransactionResponse>

Removes a restriction contract from the Paymaster.

• address: Address - The address of the restriction contract to remove.
• Returns: A ContractTransactionResponse object.

checkTransactionEligibility

async checkTransactionEligibility(contractAddress: Address, functionToCall: InterfaceAbi, args: any[] = [], overrides?: PaymasterOverrides): Promise<boolean>

Checks if a transaction is eligible to be paid for by the Paymaster, based on the added restrictions.

• contractAddress: Address - The address of the contract to call.
• functionToCall: ethers.InterfaceAbi - The definition of the function to call. Can be:
  • Human-Readable fragment - string which resembles a Solidity signature and is introduced in this blog entry. For example, function balanceOf(address) view returns (uint).
  • Parsed JSON fragment - [[Fragment]] instances - JavaScript Object desribed in the Solidity documentation.
• args: any[] (optional) - An array of arguments for the function call.
• overrides: PaymasterOverrides (optional)- An object containing overrides for the transaction (e.g., to, value, data, customData, gasLimit, maxFeePerGas, maxPriorityFeePerGas)
• Returns: true if the transaction is eligible, false otherwise.

getMinimalAllowance

async getMinimalAllowance(contractAddress: Address, functionToCall: InterfaceAbi, args?: any[], overrides?: PaymasterOverrides): Promise<BigNumberish>

Calculates the minimal allowance required for an ERC20Paymaster to pay for a transaction.

• contractAddress: Address - The address of the contract to call.
• functionToCall: ethers.InterfaceAbi - The definition of the function to call. Can be:
  • Human-Readable fragment - string which resembles a Solidity signature and is introduced in this blog entry. For example, function balanceOf(address) view returns (uint).
  • Parsed JSON fragment - [[Fragment]] instances - JavaScript Object desribed in the Solidity documentation.
• args: any[] (optional) - An array of arguments for the function call.
• overrides: PaymasterOverrides (optional)- An object containing overrides for the transaction (e.g., to, value, data, customData, gasLimit, maxFeePerGas, maxPriorityFeePerGas)
• Returns: The minimal allowance as a BigNumberish value.

Restrictions

Restrictions are external smart contracts that can be added to the Paymaster contract. These restrictions are used to enforce specific conditions or rules that must be met for a transaction to be eligible for payment by the Paymaster. Currently, there are 3 restriction types/methods: contract, user and function restrictions.

createRestriction

async function createRestriction(
  name: string,
  type: RestrictionMethod,
  runner: Signer | Wallet,
  items?: RestrictionItems,
  restrictionFactoryContractAddress?: string
): Promise<Address>

Deploys a new restriction contract based on the provided parameters.

• name: string - The name of the restriction contract to be created.
• type: RestrictionMethod - The type of restriction contract to be created. It can be one of the following: CONTRACT, USER, or FUNCTION
• runner: Signer | Wallet: A Signer or Wallet instance used for signing transactions and interacting with the Restriction Factory contract.
• items: RestrictionItems (optional) - An object containing the items (e.g., contract addresses, user addresses, function signatures with contract addresses) related to the restriction being created.
• restrictionFactoryContractAddress: Address (optional) - The address of the Restriction Factory contract. If not provided, it will be retrieved based on the chain ID.
• Returns: Address: address of the deployed restriction.

types

PaymasterParams

A tuple type representing the parameters for several methods of Paymaster instance: populatePaymasterTransaction, sendPaymasterTransaction, checkTransactionEligibility and getMinimalAllowance. Added for easier usage.

export type PaymasterParams = [Address, InterfaceAbi, any[]?, PaymasterOverrides?];

PaymasterType

export enum PaymasterType {
  ERC20,
  SPONSORED,
}

RestrictionMethod

export enum RestrictionMethod {
  CONTRACT,
  USER,
  FUNCTION,
}

PaymasterOptions

export interface PaymasterOptions {
  innerInput?: BytesLike;
  minimalAllowance?: BigNumberish;
}

PaymasterOverrides

export interface PaymasterOverrides extends Omit<TransactionRequest, 'from' | 'type' | 'gasPrice'> {
  paymasterOptions?: PaymasterOptions;
}

BaseRestrictionItem

export type BaseRestrictionItem = {
  address: string;
};

AddressOrBaseRestrictionItem

export type AddressOrBaseRestrictionItem = string | BaseRestrictionItem;

ContractItems

export type ContractItems = AddressOrBaseRestrictionItem[];

UserItems

export type UserItems = AddressOrBaseRestrictionItem[];

FunctionItems

export type FunctionItems = (BaseRestrictionItem & {
  functionSignature: string;
})[];

RestrictionItems

export type RestrictionItems = ContractItems | UserItems | FunctionItems;

typechain

export type { ContractRestriction };
export type { ERC20Paymaster };
export type { ERC20Token };
export type { Factory };
export type { FunctionRestriction };
export type { IRestriction };
export type { RestrictionFactory };
export type { SponsoredPaymaster };
export type { UserRestriction };
export { ContractRestriction__factory };
export { ERC20Paymaster__factory };
export { ERC20Token__factory };
export { Factory__factory };
export { FunctionRestriction__factory };
export { IRestriction__factory };
export { RestrictionFactory__factory };
export { SponsoredPaymaster__factory };
export { UserRestriction__factory };