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) => ...
);
Aggregator
Exposes typed functions for interacting with the Aggregator's HTTP API.
Add a bundle to an aggregator
import { Aggregator } from "bls-wallet-clients";
const aggregator = new Aggregator("https://arbitrum-goerli.blswallet.org");
const resp = await aggregator.add(bundle);
if ("failures" in resp) {
throw new Error(resp.failures.join(", "));
}
Get the bundle receipt that contains the transaction hash you can lookup on a block explorer
You will have to poll for the bundle receipt once you have added a bundle to an aggregator. The transaction hash is located on the bundle receipt. The property you need is bundleReceipt.transactionHash
. This represents the transaction hash for the bundle submitted to the Verification Gatewaty, and can be used in a block explorer.
Note this transaction is reprentative of the entire bundle submitted by the aggregator, and does not represent individual operations. To retrieve information about individual operations, use the get getOperationResults
helper method which is explained under the VerificationGateway section below.
import { Aggregator } from "bls-wallet-clients";
const aggregator = new Aggregator("https://arbitrum-goerli.blswallet.org");
const resp = await aggregator.add(bundle);
if ("failures" in resp) {
throw new Error(resp.failures.join(", "));
}
let receipt;
while (!receipt) {
receipt = await aggregator.lookupReceipt(resp.hash);
if (receipt && "submitError" in receipt) {
throw new Error(receipt.submitError);
}
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(...)
. Make sure the bls wallet you're trying to use has enough ETH to send transactions. You can either fund a wallet before it's created, or after the wallet is lazily created from its first transaction (bundle).
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,
encodedFunction: someToken.interface.encodeFunctionData("transfer", [
"0x...some address...",
ethers.BigNumber.from(1).pow(18),
]),
},
],
});
await aggregator.add(bundle);
Sending a regular ETH transaction
const amountToTransfer = ethers.utils.parseUnits("1");
const reciever = "0x1234...";
const bundle = wallet.sign({
nonce,
actions: [
{
ethValue: amountToTransfer,
contractAddress: reciever,
encodedFunction: "0x",
},
],
});
Constructing actions to be agnostic to both ETH transfers and contract interactions
const transactions = [
{
value: ethers.utils.parseUnits("1"),
to: "0x1234...",
},
];
const actions: ActionData[] = transactions.map((tx) => ({
ethValue: tx.value ?? "0",
contractAddress: tx.to,
encodedFunction: tx.data ?? "0x",
}));
const bundle = wallet.sign({
nonce,
actions,
});
Estimating and paying fees
User bundles must pay fees to compensate the aggregator. Fees can be paid by adding an additional action to the users bundle that pays tx.origin. For more info on how fees work, see aggregator fees.
Practically, this means you have to first estimate the fee using aggregator.estimateFee
, and then add an additional action to a user bundle that pays the aggregator with the amount returned from estimateFee
. When estimating a payment, you should include this additional action with a payment of zero wei, otherwise the additional action will increase the fee that needs to be paid. Additionally, the feeRequired
value returned from estimateFee
is the absolute minimum fee required at the time of estimation, therefore, you should pay slightly extra to ensure the bundle has a good chance of being submitted successfully.
Paying aggregator fees with native currency (ETH)
import { BlsWalletWrapper, Aggregator } from "bls-wallet-clients";
const wallet = await BlsWalletWrapper.connect(
privateKey,
verificationGatewayAddress,
provider,
);
const aggregator = new Aggregator("https://arbitrum-goerli.blswallet.org");
const estimateFeeBundle = wallet.sign({
nonce,
actions: [
...actions,
{
ethValue: 1,
contractAddress: aggregatorUtilitiesContract.address,
encodedFunction:
aggregatorUtilitiesContract.interface.encodeFunctionData(
"sendEthToTxOrigin",
),
},
],
});
const feeEstimate = await aggregator.estimateFee(estimateFeeBundle);
const safetyDivisor = 5;
const feeRequired = BigNumber.from(feeEstimate.feeRequired);
const safetyPremium = feeRequired.div(safetyDivisor);
const safeFee = feeRequired.add(safetyPremium);
const bundle = wallet.sign({
nonce: await wallet.Nonce(),
actions: [
...actions,
{
ethValue: safeFee,
contractAddress: aggregatorUtilitiesContract.address,
encodedFunction:
aggregatorUtilitiesContract.interface.encodeFunctionData(
"sendEthToTxOrigin",
),
},
],
});
Paying aggregator fees with custom currency (ERC20)
The aggregator must be set up to accept ERC20 tokens in order for this to work.
import { BlsWalletWrapper, Aggregator } from "bls-wallet-clients";
const wallet = await BlsWalletWrapper.connect(
privateKey,
verificationGatewayAddress,
provider,
);
const aggregator = new Aggregator("https://arbitrum-goerli.blswallet.org");
const estimateFeeBundle = wallet.sign({
nonce,
actions: [
...actions,
{
ethValue: 0,
contractAddress: tokenContract.address,
encodedFunction: tokenContract.interface.encodeFunctionData("approve", [
aggregatorUtilitiesContract.address,
1,
]),
},
{
ethValue: 0,
contractAddress: aggregatorUtilitiesContract.address,
encodedFunction: aggregatorUtilitiesContract.interface.encodeFunctionData(
"sendTokenToTxOrigin",
[tokenContract.address, 1],
),
},
],
});
const feeEstimate = await aggregator.estimateFee(estimateFeeBundle);
const safetyDivisor = 5;
const feeRequired = BigNumber.from(feeEstimate.feeRequired);
const safetyPremium = feeRequired.div(safetyDivisor);
const safeFee = feeRequired.add(safetyPremium);
const bundle = wallet.sign({
nonce: await wallet.Nonce(),
actions: [
...actions,
{
ethValue: 0,
contractAddress: tokenContract.address,
encodedFunction: tokenContract.interface.encodeFunctionData("approve", [
aggregatorUtilitiesContract.address,
safeFee,
]),
},
{
ethValue: 0,
contractAddress: aggregatorUtilitiesContract.address,
encodedFunction: aggregatorUtilitiesContract.interface.encodeFunctionData(
"sendTokenToTxOrigin",
[
tokenContract.address,
safeFee,
],
),
},
],
});
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,
);
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);
const { error } = opResults[0];
console.log(error?.actionIndex);
console.log(error?.message);
const errorData = '0x5c66760100000000.............000000000000';
const opResultError = decodeError(errorData);
console.log(opResultError.actionIndex);
console.log(opResultError.message);
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 privateKey = "0x...256 bits of private hex data here";
const signer = await initBlsWalletSigner({ chainId: 10, privateKey });
const someToken = new ethers.Contract(
...
);
const bundle = signer.sign(
{
nonce: ethers.BigNumber.from(0),
ethValue: ethers.BigNumber.from(0),
contractAddress: someToken.address,
encodedFunction: someToken.interface.encodeFunctionData("transfer", [
"0x...some address...",
ethers.BigNumber.from(10).pow(18),
]),
},
);
})();
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"
Troubleshooting tips
- Make sure your bls-wallet-clients package is up-to-date and check out our releases page for info on breaking changes.
- Check network values such as the verification gateway address or the aggregator url are up-to-date. The most up-to-date values are located in the relevant network config file. If you're deploying to a custom network, you'll have to check these against your own records as these won't be in the network directory.