@0xpass/account v0.2.10

Introduction

0xpass allow DAPPs developers access to Smart Contract Wallets. These wallets can be DAPPs specific or User specific. You must read about Wallets section before using the SDK.

Getting Started

A guide for adding a 0xpass SDK to your application & start bundling transactions. There are two parts of the documentation, bundling transaction and sponsoring gas.

For both of them you would need to install our SDK. For sponsoring gas, you will have to first create a paymaster contract. To know more about how to create a paymaster contract, read here.

What you'll need

• Node.js version 16.14 or above:
  • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

Installing SDK

Our SDK is currently under development, we will be hosting it on NPM soon. The Client SDK will be available in JavaScript with full TypeScript support.

npm install @0xpass/account

yarn add @0xpass/account

Wallets

Smart Contract Wallets (SCW) allows DAPP developer to bundle multiple transaction & pay gas fees for their users. You must create a SCW using our SDK for every user. The final bundled call will initiate from user's SCW. If you want to transfer the final assets to the user's current EOA, then you MUST send the transaction to transfer the assets from SCW to EOA separately.

To know how to create a SCW for a user see Dapp specific wallets.

:warning: Wallet is not deployed instantly, it will only be deployed once you do the first transaction, resulting in a higher gas fees in the first transaction. Though the scw address is deterministic and funds can be sent to the address.

Dapp specific wallets

Install our SDK using instructions here.

Initiate a wallet

Create a Smart Contract Wallet for a user. You MUST pass a signer while creating the SCW. The signer will have the custody of the SCW.

import { Signer } from 'ethers'
import { AccountProvider } from '@0xpass/account'

/**
 * You can get signer using either the private key
 * const signer: Signer = new ether.Wallet(privateKey);
 * You can get signer if user has an EOA using wagmi.sh
 * const { data: signer } = useSigner();
 */

/* Once you have signer & provider, create user's SCW */

/**
 * @param provder - any BaseProvider from ethers (JSONRpcProvider | window.ethereum | etc)
 * @param signer - this will be the owner of the SCW that will be deployed.
 */
const accountProvider: AccountProvider = await AccountProvider.getAccountForOwner(provider, signer)

Once the SCW has been initiated, you can use it as a normal signer with ethers/web3/etc to connect & send bundled transactions.

Executing transactions

You can get Signer from the AccountProvider we created above & start using it normally as you would use an EOA.

const accountSigner = accountProvider.getSigner()
const greeter = new ethers.Contract(GREETER_ADDR, GreeterArtifact.abi, accountSigner)

const tx = await greeter.addGreet({
  value: ethers.utils.parseEther('0.0001'),
})
console.log(tx)

Bundling transactions

You can also send multiple transactions within a single transaction using SCW. Think of approvide ERC20 tokens & deposit them in a single transaction with a single signature from the users.

Read more about how here.

:warning: The transactions sent using ethers/web3/etc won't be by default bundled or sponsored. Use sendTransactions instead to bundle transactions, see Bundle Transactions. If you want to sponer, make sure you connect a paymaster, see Gassless Experience

Bundle Transactions

Bundling transactions opens up a plathora of possibilities. We have listed a few of them as example:

1. Users won't have to do two transactions for approving an ERC20 token & then depositing it.
2. You can easily support depositing of any ERC20 in your app. Just add a transaction to swap user's token to your preffered token using any Dex.
3. Modular Contract designs, deploy only specific contract modules and then join them off-chain using a bundler transactions.

Single chain bundling

You must have initialised iSDK & created a AccountProvider. We have exposed a function in a SCWSigner called sendTransactions using which you can send multiple transactions.

const accountSigner = accountProvider.getSigner()
const greeter = new ethers.Contract(GREETER_ADDR, GreeterArtifact.abi, accountSigner)

const transactionData = greeter.interface.encodeFunctionData('addGreet')

const tx = await accountProvider.sendTransactions([
  {
    to: GREETER_ADDR,
    value: ethers.utils.parseEther('0.0001'),
    data: transactionData,
  },
  {
    to: GREETER_ADDR,
    value: ethers.utils.parseEther('0.0002'),
    data: transactionData,
  },
])
console.log(tx)

await accountProvider.sendTransactions([
  {
    to: ERC20_TOKEN_ADDR,
    value: ethers.utils.parseEther('0.1'),
    data: TOKEN.interface.encodeFunctionData('approve', [
      spenderAddress,
      ethers.utils.parseEther(amount * 10), // getting approval from 10 times the amount to be spent
    ]),
  },
  {
    to: myContract.address,
    value: ethers.utils.parseEther('0.1'),
    data: myContract.interface.encodeFunctionData('stake', [ERC20_TOKEN_ADDR, ethers.utils.parseEther(amount)]),
  },
])

Cross chain bundling

:warning: Cross-chain Bundling will be coming soon, which will enable you to add bridging transactions to your transactions as well.

Gassless Experience

Cupkaes SDK will enable conditional gassless experience, which includes partial gas-sponsoring. This enables you to have complex integrations like: sponsoring of gas on ethereum upto $5 and 100% on L2/sidechain.

Before you can start sponsoring gas, you must deploy a paymaster contract. The paymaster MUST be staked & should have enough deposit to sponsor for gas. If the deposited amount becomes lesser than the gas required then your transactions will start failing.

Paymaster

Paymaster is a contract that sponsors gas fees on behalf of users. To know more about how it works, read in the architecture section.

To enable gas sponsoring these are the steps you must do:

1. Deploy a paymaster
2. Stake paymaster
3. Register a webhook
4. Integrate with frontend

Deploy a paymaster

Head to our website https://comingsoon@0xpass and follow the steps shown in the video below to deploy your first paymaster.

<iframe width="720" height="406" src="https://www.youtube-nocookie.com/embed/jreqzJMzR5s" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Stake & deposit funds

Once you have created your paymaster, you will have to stake your funds. The Minimum stake as of now is x MATIC with a lock-in of 7 days. The stake is to make sure no fraudulant activity can be performed by the paymaster. The staked funds will be deductded if any such fraudulant activity is found.

:warning: You must have enough deposit left to cover for 100% of the gas fees even if you only want to sponsor a portion of it. If desposit is not enough, the transaction will be reverted.

Learn more about how your stake can be slashed more in detail here.

Register webhook

You will have to register a webhook, where we will be sending the a POST request to verify the sponsoring of the gas.

The requst will have the following body:

{
  "auth_code": "b110a339-ff6c-4456-8adb-b236a3da11d3",
  "timestamp": 1662805504483,
  "userOperation": {
    "sender": "0xadb2...asd4", // Sender's address of the SCW
    "maxGasCost": 123, // you can use this as the total of all the above gas breakup & use this to make decision of sponsoring
    "paymasterDeposit": 123, // the amount of deposit left in your paymaster contract, you can send refill transactions using this if you want to
    "paymasterAddress": "0x23rr...", // your paymaster contract address, you should send money to this address if paymasterDeposit is approaching zero
    "transactions": [
      // this is the array of transactions that your frontend SDK included for bundling
      {
        "to": "0x123..",
        "value": 4, // value in ethers
        "data": "0xadsf..." // call data your SDK passed
      }
    ],
    // The following fields are part of the UserOperation that will be used to generate signature, you can ignore these if you are using our paymaster SDK
    "nonce": 123,
    "initCode": "0xAxvd3r....adfsg4r", //init code, if not empty means that this wallet doesn't exist and will be deployed in this transaction along with executing the required transaction
    "callData": "0xsdfdasf...000", // call data of the execution
    "callGas": 123, // the amount of gas the main execution of transaction will take
    "verificationGas": 123, //the constant amount of gas which is required to verify sender's ownership
    "preVerificationGas": 123, // the constant amount of gas which is required by the bundler for processing the transaction
    "maxFeePerGas": 123, // the maximum gas price, this depends on how busy the network is
    "maxPriorityFeePerGas": 123 // the fee that will be used to tip the miner
  }
}

You must verify auth_code to check if the call is from our service or not. You will see the auth_code once you register a success webhook.

You must return with a 200 code if you agree to sponsor the transaction. If you choose not to sponsor, you must return with a 403 - Forbidden status code response.

Integrate with frontend

You will have to connect your paymaster with the SCW you created in Wallets section.

import { PaymasterAPI } from '@0xpass/account'

// You can get the your API KEY when you create a paymaster, every paymaster has a different API KEY

/* Connect to us to get Paymaster URL & Paymaster API KEY */
const paymasterAPI = new PaymasterAPI(process.env.REACT_APP_PAYMASTER_URL, process.env.REACT_APP_PAYMASTER_API_KEY)

/* Connect your paymaster to the provider */
accountProvider.connectPaymaster(paymasterAPI)

/* Do transaction as normal */
const accountSigner = accountProvider.getSigner()
const greeter = new ethers.Contract(GREETER_ADDR, GreeterArtifact.abi, accountSigner)

const tx = await greeter.addGreet({
  value: ethers.utils.parseEther('0.0001'),
})
console.log(tx)

/* Disconnect if you don't want to sponsor amny further */
accountProvider.disconnectPaymaster()