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'
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:
- Users won't have to do two transactions for approving an ERC20 token & then depositing it.
- 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.
- 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),
]),
},
{
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:
- Deploy a paymaster
- Stake paymaster
- Register a webhook
- 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",
"maxGasCost": 123,
"paymasterDeposit": 123,
"paymasterAddress": "0x23rr...",
"transactions": [
{
"to": "0x123..",
"value": 4,
"data": "0xadsf..."
}
],
"nonce": 123,
"initCode": "0xAxvd3r....adfsg4r",
"callData": "0xsdfdasf...000",
"callGas": 123,
"verificationGas": 123,
"preVerificationGas": 123,
"maxFeePerGas": 123,
"maxPriorityFeePerGas": 123
}
}
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'
const paymasterAPI = new PaymasterAPI(process.env.REACT_APP_PAYMASTER_URL, process.env.REACT_APP_PAYMASTER_API_KEY)
accountProvider.connectPaymaster(paymasterAPI)
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)
accountProvider.disconnectPaymaster()