bls-wallet-clients

BLS Wallet Clients

Client libraries for interacting with BLS Wallet components

Network Config

Deployed contract addresses and metadata.

import { NetworkConfig, getConfig } from 'bls-wallet-clients';

const netCfg: NetworkConfig = await getConfig(
  '/path/to/network/config',
  async (path) => ... /* fetch, fs.readFile, etc. */
);
// Read from netCfg.addresses.verificationGateway, etc.

Aggregator

Exposes typed functions for interacting with the Aggregator's HTTP API.

import { Aggregator } from 'bls-wallet-clients';

const aggregator = new Aggregator('https://arbitrum-goerli.blswallet.org');
const resp = await aggregator.add(bundle); // See BlsWalletWrapper section below
// Aggregator did not accept bundle
if ("failures" in resp) {
  throw new Error(resp.failures.join(", "));
}

let receipt;
while (!receipt) {
  receipt = await aggregator.lookupReceipt(resp.hash);
  // There was an issue submitting the bundle on chain
  if (receipt && "submitError" in receipt) {
    throw new Error(receipt.submitError);
  }
  // Some function which waits i.e. setTimeout
  await sleep(5000);
}

BlsWalletWrapper

Wraps a BLS wallet, storing the private key and providing .sign(...) to produce a Bundle, that can be used with aggregator.add(...).

import { BlsWalletWrapper } from 'bls-wallet-clients';

const wallet = await BlsWalletWrapper.connect(
  privateKey,
  verificationGatewayAddress,
  provider,
);

const bundle = wallet.sign({
  nonce: await wallet.Nonce(),
  actions: [
    {
      ethValue: 0,
      contractAddress: someToken.address, // An ethers.Contract
      encodedFunction: someToken.interface.encodeFunctionData(
        "transfer",
        ["0x...some address...", ethers.BigNumber.from(1).pow(18)],
      ),
    },
    // Additional actions can go here. When using multiple actions, they'll
    // either all succeed or all fail.
  ],
});

await aggregator.add(bundle);

VerificationGateway

Exposes VerificationGateway and VerificationGateway__factory generated by typechain to enable typed interactions with the VerificationGateway.

import { VerificationGateway__factory } from 'bls-wallet-clients';

const verificationGateway = VerificationGateway__factory.connect(
  verificationGatewayAddress,
  signer, // An ethers signer
);

await verificationGateway.processBundle(bundle);

You can get the results of the operations in a bundle using getOperationResults.

import { getOperationResults, decodeError } from 'bls-wallet-clients';

...

const txn = await verificationGateway.processBundle(bundle);
const txnReceipt = txn.wait();
const opResults = getOperationResults(txnReceipt);

// Includes data from WalletOperationProcessed event,
// as well as parsed errors with action index
const { error } = opResults[0];
console.log(error?.actionIndex); // ex. 0 (as BigNumber)
console.log(error?.message); // ex. "some require failure message"

// If you want more granular ability to decode an error message
// you can use the decodeError function.
const errorData = '0x5c66760100000000.............000000000000';
const opResultError = decodeError(errorData);
console.log(opResultError.actionIndex); // ex. 0 (as BigNumber)
console.log(opResultError.message); // ex. "ERC20: insufficient allowance"

Signer

Utilities for signing, aggregating and verifying transaction bundles using the bls signature scheme. Bundles are actioned in contracts.

Useful in the aggregator for verification and aggregation, and in the extension for signing and aggregation.

import ethers from "ethers";
import { initBlsWalletSigner } from "bls-wallet-clients";

(async () => {
  const signer = await initBlsWalletSigner({ chainId: 10 });

  const privateKey = "0x...256 bits of private hex data here";

  const someToken = new ethers.Contract(
    // See https://docs.ethers.io/v5/getting-started/
  );

  const bundle = signer.sign(
    {
      nonce: ethers.BigNumber.from(0),
      ethValue: ethers.BigNumber.from(0),
      contractAddress: someToken.address,

      // If you don't want to call a function and just send `ethValue` above,
      // use '0x' to signify an empty byte array here
      encodedFunction: someToken.interface.encodeFunctionData(
        "transfer",
        ["0x...some address...", ethers.BigNumber.from(10).pow(18)],
      ),
    },
    privateKey,
  );

  // Send bundle to an aggregator or use it with VerificationGateway directly.
})();

Local Development

Setup

yarn install

Build

yarn build

Tests

yarn test

Use in Extension or another project

yarn build
yarn link
cd other/project/dir
yarn "link bls-wallet-clients"