Create gas sponsored developer wallet set

Create a gas sponsored developer wallet and execute contract function using the wallet

Creating a user gas-sponsored developer wallet set and wallet is nearly identical to creating a standard developer wallet, with minor distinctions. In this article, we'll delve into these distinctions. Wallets generated from a standard wallet set are known as externally owned accounts (EOAs), while wallets created from gas-sponsored wallet sets are contract accounts (following the EIP-4337 standard for smart contract accounts). Both types of wallets possess the capability to sign messages, execute digital asset transfers, and interact with smart contracts. However, for the purpose of this tutorial, we will focus on executing certain smart contract functions, as we have already covered token transfers in the previous article.

Prerequisites

• Create a Developer Account and acquire an API key in the Dashboard.

• Create your first developer wallet

Please note that you can not repeat idempotencyKey, except the initial transaction failed as it will raise a 401 error.

1. Create Gas Sponsored Wallet Set

To establish a gas-sponsored wallet set, you can initiate a request to POST /wallet-sets/developer/create, similar to the process for creating a standard wallet set. However, there are two additional parameters to consider: isGasSponsored and sponsorOnlyTransfersToWalletSetAddresses, both of which are boolean values. By default, isGasSponsored is set to false, while sponsorOnlyTransfersToWalletSetAddresses is set to true.

To create a gas-sponsored wallet address, you should set isGasSponsored to true. Depending on whether you want to sponsor all user transactions, including transfers outside your business ecosystem, you can choose to set sponsorOnlyTransfersToWalletSetAddresses to false. On the other hand, if you wish to sponsor only transactions within your ecosystem, which includes digital asset transfers among your business users and contract interactions, you can proceed to set sponsorOnlyTransfersToWalletSetAddresses to true.

For the purpose of this tutorial we'll be creating a gas sponsored wallet set to sponsor all users' transactions gas fees.

curl --request POST \
     --url 'https://api.planbok.io/v1/wallet-sets/developer/create' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "1681b219-b430-48f5-8c93-50dd2d4139b5",
          "name": "Test Gas Sponsored Wallet Set",
          "isGasSponsored": true,
          "sponsorOnlyTransfersToWalletSetAddresses": false
     }'

{
    "status": 201,
    "walletSet": {
        "id": "6519c5d92b8a095cb141ca0f",
        "name": "Test Gas Sponsored Wallet Set",
        "custodyType": "DEVELOPER",
        "userId": "650875cf2de8864ba34d2d8c",
        "createAt": "2023-10-01T09:11:46.325Z",
        "updatedAt": "2023-10-01T09:11:46.325Z"
    },
    "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>",
    "message": "Wallet set created successfully"
}

2. Create Wallet

Creating a wallet within the gas-sponsored wallet set follows the same procedure as for a standard wallet set. The only distinction lies in the Response Body, where the accountType will be SMART-ACCOUNT instead of EOA for the standard wallet set. Initiate a request to POST /wallets/developer/create, utilising the walletSet.id and walletSetSecretCipherText obtained from step 1, to create a wallet.

curl --request POST \
     --url 'https://api.planbok.io/v1/wallets/developer/create' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "bdcb308f-179e-4786-b870-4b6177c9e246",
          "blockchains": ["ETH-SEPOLIA"],
          "username": "john_doe",
          "userRefId": "8b9b8143-b580-4173-a742-f5ee2fe45c1f",
          "walletSetId": "6519c5d92b8a095cb141ca0f",
          "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>"
     }'

Response Body

{
    "status": 201,
    "wallets": [{
        "id": "651c2d6981e7406eca0ac139",
        "accountType": "SMART-ACCOUNT",
        "address": "0xa0780f1403419ad992cA0420AAb81a4562e179dd",
        "blockchain": "ETH-SEPOLIA",
        "custodyType": "DEVELOPER",
        "username": "john_doe",
        "userRefId": "8b9b8143-b580-4173-a742-f5ee2fe45c1f",
        "walletSetId": "6519c5d92b8a095cb141ca0f",
        "userId": "659235cf2de7864ba34d2d8d"
    }],
    "message": "Wallet created successfully"
}

3. Lookup business gas sponsor address and balance

Lookup your business gas sponsor wallet address and balance by making a request to GET /wallet-sets/{id}/sponsor/{blockchain}/developer.

Variables explained as follows:

• id is the wallet set id. Using 6519c5d92b8a095cb141ca0f for this tutorial

• blockchain is the preferred blockchain you'd like to fund. Since the created wallet uses ETH-SEPOLIA we'll be using the same blockchain.

curl --request GET \
     --url 'https://api.planbok.io/v1/wallet-sets/6519c5d92b8a095cb141ca0f/sponsor/ETH-SEPOLIA/developer' \
     --header 'accept: application/json' \
     --header 'planbok-x-api-key: <API_KEY>'

{
    "status": 200,
    "sponsor": {
        "address": "0x48347FD5f31c499A8d88A68680910178a23FA785",
        "amount": "0.0 ETH"
    }
}

4. Top-up sponsor address balance

Acquire Sepolia ETH tokens through the Alchemy Sepolia Faucet and proceed to transfer them to the sponsor wallet address provided in the response body from running the previous step and repeat the previous step to confirm that your balance has been successfully updated, before proceeding.

5. Execute contract transaction

Make a request to POST /transactions/contract-execution/developer just like in the example below. 0x468BCa19cf28f5b282F1702006481a893Aa2cde8 is the contract address to a Mock USDT token and we want to approve 0x2367BFF998714005b227E8AD3FA425074bee5914 to spend 1000000000000 USDT from our balance.

curl --request POST \
     --url 'https://api.planbok.io/v1/transactions/contract-execution/developer' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "f710e18f-b4e7-477a-9f13-e08b856b0944",
          "abiFunctionSignature": "approve(address,uint256)",
          "abiParameters": ["0x2367BFF998714005b227E8AD3FA425074bee5914", "1000000000000000000000000000000"],
          "contractAddress": "0x468BCa19cf28f5b282F1702006481a893Aa2cde8",
          "walletId": "6519c911bd92a55b47fc3b97",
          "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>"
     }'

Response Body

{
    "status": 201,
    "data": {
        "id": "651cb86e43e7856f778da99f",
        "state": "PENDING"
    }
}

When executing a contract function and you're required to send value enter the value in ether instead of wei e.g. 0.1 instead of 100000000000000000

6. Check Transaction State

Make a request to GET /transactions/{id}/developer?walletId={walletId} to return the specific transaction details using the id from previous step response body.

curl --request GET \
     --url 'https://api.planbok.io/v1/transactions/651cb86e43e7856f778da99f/developer?walletId=651c2d6981e7406eca0ac139' \
     --header 'accept: application/json' \
     --header 'planbok-x-api-key: <API_KEY>'

{
    "status": 200,
    "data": {
            "id": "651cb86e43e7856f778da99f",
            "sourceAddress": "0xa0780f1403419ad992cA0420AAb81a4562e179dd",
            "destinationAddress": "0x468BCa19cf28f5b282F1702006481a893Aa2cde8",
            "nonce": 0,
            "walletId": "6508cea4093d416d49a37bae",
            "blockchain": "ETH-SEPOLIA",
            "state": "COMPLETE",
            "txHash": "0xb1b055df1fd9d8503cfae536545f4d88071e1ea71e69926d1f11a2308768e258",
            "blockHash": "0x6ceeb00881a476c3ad31c5919d081506a40217fc35014661cb89b96e385eb69e",
            "blockHeight": 9815431,
            "operation": "CONTRACT-EXECUTION",
            "abiFunctionSignature": "approve(address,uint256)",
            "abiParameters": [
                "0x2367BFF998714005b227E8AD3FA425074bee5914",
                "1000000000000000000000000000000"
            ],
            "firstConfirmDate": "2023-10-05T19:37:20.932Z",
            "networkFee": "0.001633401 gETH",
            "createdAt": "2023-10-05T19:26:18.802Z",
            "updatedAt": "2023-10-05T19:27:26.187Z"
        }
}

When the transaction.state is COMPLETE, this means that the token has sent from the your wallet to the destination wallet.

You can also check the transaction using the txHash on Sepolia Etherscan and check that you have given the allowance to the address in the abiParameters. Inspect the balance of sponsor wallet and compare with the previous balance, the difference is the amount of gas used to execute the transaction.