🚀 @txfusion/txsync-viem

📌 Overview

@txfusion/txsync-viem 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 @txfusion/txsync-viem 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
createExtension - function that creates an extension which can be added to the Paymaster

🛠 Prerequisites

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

📥 Installation & Setup

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

🧑‍🍳 Examples

The complete examples with various use cases are available here.

📝 SDK API

getPaymaster

async function getPaymaster(address: Address, walletClient: WalletClient, publicClient: PublicClient): 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.
walletClient: WalletClient instance for signing and sending transactions.
publicClient: PublicClient public client instance for getting public functions.
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, walletClient: WalletClient, publicClient: PublicClient, paymasterType: PaymasterType, chainId: ChainId, token?: Address)

address: Address - The address of the Paymaster contract.
walletClient: WalletClient - A WalletClient instance for signing transactions.
publicClient: PublicClient - A PublicClient instance for getting public functions.
paymasterType: PaymasterType - type of Paymaster (ERC20Paymaster or SponsoredPaymaster).
chainId: ChainId - The ID of the chain the Paymaster contract is deployed on.
token: Address (optional) - The address of the ERC20 token used by the ERC20Paymaster.

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(address: Address, abi: Abi | readonly unknown[], functionName: string, args: any[] = [], overrides?: PaymasterOverrides):

Populates and sends a transaction using the Paymaster.

address: Address - The address of the contract to call.
abi: Abi | readonly unknown[] - The ABI of the contract to call.
functionName: string - The name of the function to call.
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 hash of the transaction.

getBalance

async getBalance(): Promise<bigint>

Gets the balance of the Paymaster contract.

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

estimateGas

async estimateGas(address: Address, abi: Abi | readonly unknown[], functionName: string, args?: any[], overrides?: PaymasterOverrides): Promise<bigint>

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

address: Address - The address of the contract to call for which to estimate the gas.
abi: Abi | readonly unknown[] - The ABI of the contract to call for which to estimate the gas.
functionName: string - The name of the function to call for gas estimation.
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 estimated gas limit as a bigint value.

getPaymasterContract

getPaymasterContract(): ERC20PaymasterContract | SponsoredPaymasterContract

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

Returns: An instance of the paymaster contract in ERC20PaymasterContract or SponsoredPaymasterContract type.

addRestriction

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

Adds an extension to the Paymaster.

address: Address - The address of the extension contract to add.
Returns: A hash of the extension.

getRestrictions

async getExtensions(): Promise<string[]>

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

Returns: An array of extension contract addresses.

removeExtension

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

Removes a extension contract from the Paymaster.

address: Address - The address of the extension contract to remove.
Returns: A hash of the transaction.

Extensions

Extensions are external smart contracts that can be added to the Paymaster contract. These extensions 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 extension types/methods: contract, user and function extensions.

createExtension

async function createExtension(
  name: string,
  type: ExtensionMethod,
  wallet: WalletClient,
  client: unknown,
  items?: ExtensionItems,
  restrictionFactoryABI?: Abi,
  restrictionFactoryContractAddress?: Address
): Promise<Address>

Deploys a new extension contract based on the provided parameters.

name: string - The name of the extension contract to be created.
type: ExtensionMethod - The type of extension contract to be created. It can be one of the following: CONTRACT, USER, or FUNCTION
wallet: WalletClient: A WalletClient instance used for signing transactions and interacting with the Restriction Factory contract.
client: PublicClient: A PublicClient instance used for writing public transactions.
items: ExtensionItems (optional) - An object containing the items (e.g., contract addresses, user addresses, function signatures with contract addresses) related to the extension being created.
restrictionFactoryABI: Abi (optional) - The ABI of the Restriction Factory contract. If not provided, it will be retrieved based on the chain ID.
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 extension.

types

PaymasterParams

A tuple type representing the parameters for several methods of Paymaster instance, like sendPaymasterTransaction. Added for easier usage.

export type PaymasterParams = {
  /** The address of the paymaster. */
  paymaster: Address;
  /** The bytestream input for the paymaster. */
  paymasterInput: BytesLike;
};

PaymasterType

export enum PaymasterType {
  ERC20,
  SPONSORED,
}

ExtensionMethod

export enum ExtensionMethod {
  CONTRACT,
  USER,
  FUNCTION,
}

PaymasterOptions

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

PaymasterOverrides

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

BaseRestrictionItem

export type BaseRestrictionItem = {
  address: Address;
};

AddressOrBaseRestrictionItem

export type AddressOrBaseRestrictionItem = Address | BaseRestrictionItem;

ContractItems

export type ContractItems = AddressOrBaseRestrictionItem[];

UserItems

export type UserItems = AddressOrBaseRestrictionItem[];

FunctionItems

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

RestrictionItems

export type ExtensionItems = ContractItems | UserItems | FunctionItems;


## 🤝 Contributing

We welcome contributions from the community! If you're interested in contributing to the `@txfusion/txsync-viem` JavaScript SDK,
please take a look at our [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for guidelines and details on the process.

Thank you for making `@txfusion/txsync-viem` JavaScript SDK better! 🙌