HumanWalletSDK

Description

HumanWallet is a library that introduces the concept of Account Abstraction to simplify the management of user wallets.

A problem to solve

To date, the only way to launch a transaction or even a smart contract interaction, has been through an Externally Owned Account (EOA). This approach has several limitations:

Transaction Fees: Users must ensure they have enough funds to cover transaction fees on all networks they are connected to (Ethereum mainnet, Polygon, etc.).

Security: Custody of the private keys rests entirely with the owner of the EOA. Loss of these keys results in the inability to access wallet funds.

Solution: Account Abstraction

By implementing the concept of Account Abstraction, HumanWallet offers:

Flexibility: Allows users to interact with various networks without worrying about transaction fees.

Improved Security: Facilitates secure wallet management when interacting with smart contract wallets.

Installation

The library supports the following formats: commonjs, ESM Modules and UMD (unpackage).

Run to install:

npm i @tutellus/humanwalletsdk

Import the library:

import { HumanWalletSDK } from "@tutellus/humanwalletsdk"

Initialization

To create an instance of the library, we must provide the following parameters in the constructor by executing the build() method.

The library has to be instantiated only once as it is expected to be used as a singleton:

HumanWalletSDK.build({
  projectId,
  options: {
    MAX_RETRIES: 50,
    INTERVAL: 5000,
  },
})

Property projectId, is mandatory. All options have default values.

Constructor description

• projectId (String): Project key. Must be managed per environment/blockchain.
• options (Object): Library configuration using the following parameters:
  • MAX_RETRIES (Number): 5,
  • INTERVAL: (Time in milliseconds) 10000,

Aditional options params:

• FIELDS (Array): title | description | status : Search/filter fields
• OFFSET: 0,
• LIMIT: 10,
• ORDER_BY: "modifiedAt",
• ORDER_DIRECTION: ASC | DESC,

Initialization

Once the library is instantiated, we use the connect method to inject the accessToken in JWT format and the provider

Both accessToken and provider parameters are required:.

• accessToken (String): Access Token of the user who is going to use HumanWallet.
• provider (Provider): Web3 provider with signer.

Implementation example in ReactJS using your provider:

const [connected, setConnected] = useState(false)

useEffect(() => {
  if (web3Provider && accessToken) {
    if (!connected) {
      setConnected(true)
      humanSDK.connect({
        provider: web3Provider,
        accessToken,
      })
    }
  }
}, [web3Provider, accessToken, connected, setConnected])

HumanWallet address deployment

When the library is instantiated, the deployment of what will be the address of the smart contract begins automatically. We can monitor this deployment by listening to the humanStatus event:

humanSDK.events().on("humanStatus", async (human) => {
  const response = await humanSDK.getProposals()
})

The callback of the humanStatus event returns an object where we can check out some properties such as: address, email, status. etc.

const humanStatusResponse = {
  address : "0x0C2b9AA910cf7e36465B302c63295EA8a8682D98"
  chainId : "0x13881"
  email : "[email protected]"
  status : "CONFIRMED"
  userId : "7c1e83d0-d7e4-4c58-918c-1f6ff851ffc4"
  // [...]
}

Overview of HumanWalletSDK methods:

As an Account Abstraction, the transactions that we would normally make with an EOA are now called proposals. Proposals can be with or without two-factor authentication (2FA). They will go through the following states:

• PENDING
• SIGNABLE
• PROCESSED
• EXECUTING
• EXECUTED
• CONFIRMED
• REVERTED

Events emmitted

Every time a new proposal is launched, it progresses and goes through each of the states seen previously, emitting a specific event with the following name:

• proposalPending
• proposalSignable
• proposalProcessed
• proposalExecuting
• proposalExecuted
• proposalConfirmed
• proposalReverted

A statusUpdate event is also emitted upon state changes with the number of proposals in each of the states for statistical purposes, although it is volatile and is reset with each instantiation.

isReady() Method

The library has the isReady() method that returns a boolean indicating that the status of HumanWallet is CONFIRMED

humanSDK.isReady() || true | false

requestProposal({ title, calls, description })

This method allows you to request a proposal for the execution of calls to contracts, this can be a transfer of tokens or a minting. We will need to provide the following parameters to the function:

• title (String): proposal title
• description (String): proposal description. (optional)
• calls (Array[CallsInfo]): Array of objects with information about contract calls.

Example to mint 10 tokens using encodeFunctionData from ethers:

const contractInterface = new ethers.utils.Interface(CONTRACT.abi)
const calldata = contractInterface.encodeFunctionData("mint", [
  "0x0C2b9AA910cf7e36465B302c63295EA8a8682D98", // HumanWallet address
  ethers.utils.parseEther("10"),
])

HumanWalletSDK.requestProposal({
  title,
  description,
  calls: [
    {
      target: "0x2CEDFf179BF88F7B4b1FFF9ca6d53393E956B74F", // Contract address
      method: "mint(address,uint256)",
      data: calldata,
      value: "0",
    },
  ],
})

Managing the status of a proposal

Every time we execute the requestProposal method, the library emits a generic event called proposalUpdate. To set a listener:

humanSDK.events().on("proposalUpdate", callback)

Additionally, we can update the status of the proposal by listening to the different events that are emitted. (proposalSignable, proposalExecuted, proposalProcessed, etc.)

To monitor a specific state change, we can listen to the corresponding event:

humanSDK.events().on("proposalConfirmed", ({ proposal }) => {
  console.log(`Proposal with ID: ${proposal._id} has been confirmed`)
})

getProposals()

If we do not provide any parameters to this function, we obtain the list of all transaction proposals performed in this HumanWallet address. If we provide any of these parameters we can filter results by:

• ids (Array[String]): Array of ids of proposals to list.
• fields (Array[String]): Fields to search.
• search (String): Text to search.
• offset (Number): Number of proposals to skip.
• limit (Number): Number of proposals to get.
• orderBy (String): Order of the results. Possible values ASC, DESC. Default value is: DESC
• orderDirection (String): Field to order results. Default value: nonce

Filtering proposals:

Example of a request with filtering by status field and CONFIRMED type:

const confirmed = await humanSDK.getProposals({
  fields: ["status"],
  search: "CONFIRMED",
  offset: 0,
  limit: 10,
})

getProposal({ proposalId })

Method to obtain the information of a proposal based on in id.

• proposalId (String): Identifier of the proposal.

confirmProposal({ proposalId, code })

Method to confirm a proposal when 2FA is necessary.

• proposalId (String): Identifier of the proposal
• code (String): 2FA code of the proposal

Every time we execute this method, the library emits an event of type proposalUpdate Setting a listener:

humanSDK.events().on("proposalUpdate", callback)

Doing so, the callback function will return an object to monitor the status as the proposal progresses. The status can be: PENDING, SIGNABLE, PROCESSED, EXECUTING, EXECUTED, CONFIRMED, or REVERTED.

getTokensBalance({ address, tokens })

Method to get the tokens balance of a HumanWallet address.

• address (Address): Address from which we will make the query.
• tokens (Array[TokenInfo]): Array of objects with token information.

Additional methods

The library exposes some methods to obtain the following additional information:

TokenInfo

• token: (Address) Address of the token
• type: (String) Token type. Possible values: ERC20 | ERC721 | ERC721Enumerable | ERC1155 | ERC4626
• ids: ([String]) In the case of ERC1155, array of ids of the tokens to be consulted.

Debugging

The library has a logger that reports in the browser console if a key debug is found in localStorage with the following content:

| Action to debug | Key | Value | | ---------------- | ----- | ------------------- | | SDK instance | debug | hw:index | | SDK events | debug | hw:monitor | | All | debug | hw:* |

Log example:

// SDK instance:

hw:index HumanWalletSDK constructor....
hw:index HumanWalletSDK ID: FyhcA_ACtN0ehBItj7yEo (31ms)
hw:index 💵 TokenBalance 610 (2465ms)
hw:index 🚀 filter with ['32c677ee-6851-4bb7-a57a-143ff07d5c96'] (7421ms)

// SDK events:

hw:monitor ⏳ UPDATING... (3ms)
hw:index 🚀 filter with ['32c677ee-6851-4bb7-a57a-143ff07d5c96'] (4ms)
hw:monitor 📝 ADD TO MONITORIZE 32c677ee-6851-4bb7-a57a-143ff07d5c96 CONFIRMED (1334ms)
hw:monitor 🚀 EMITED proposalConfirmed 32c677ee-6851-4bb7-a57a-143ff07d5c96 (2ms)
hw:monitor 🚀 EMITED statusUpdate (0ms)