EthDriver

This page describes documentation specific to the Ethereum ChainDriver named as EthDriver created by the Blockin team. It is implemented using the Moralis API and the ethers.js library for Ethereum. For BitBadges, it uses the official BitBadges API.

Check out blockin-eth-driver-minified for a version without asset verification and Moralis API (smaller size).

Installation and Initialization

First, npm install blockin-eth-driver

Then, import via import EthDriver from 'blockin-eth-driver';

To initialize a new instance, run:

const EthereumDriver = new EthDriver(CHAIN_ID, {
    apiKey: MORALIS_API_KEY
});

You may declare it without the API key and Moralis Details via new EthDriver(CHAIN_ID, undefined);CHAIN_ID should be set to a valid Moralis chain ID.

Note only some EVM chains are supported by Moralis, but if you do not need NFT sign-ins, this driver can support any EVM chain.

Visit the Moralis quick start documentation for more information on how to use their API and get the details specified above. Note that it is recommended that these details should be kept private.

Signatures

See here for an example of implementing signatures in a compatible format.

import { signMessage } from "@wagmi/core"

const signChallenge = async (message: string) => {
  const sig = await signMessage({
    message: message,
  })

  return {
    message,
    signature: sig,
  }
}

BitBadges

Note to use the BitBadges API and query badges, you must set a valid environment variable for process.env.BITBADGES_API_KEY.

Scheme

For anything where an Ethereum asset is needed in EthDriver, we use the contract address for the collectionId. For BitBadges, we use the collectionId.

BitBadges assetIds must be in the form of [{ start: 1, end: 10 }, ....]

Ethereum assetIds must be in the form of ["1", "2", ...]

ownershipTimes (if blank, we query current time) can either be a valid JS Date string or in UNIX milliseconds via [{ start: 1, end: 1000000 }]

{
  collectionId: "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
  assetIds: ["15"],
  mustOwnAmounts: [{ start: 0, end: 0 }],
  chain: 'Ethereum',
},
{
  collectionId: 1,
  assetIds: [{ start: 1, end: 1 }],
  mustOwnAmounts: [{ start: 0, end: 0 }],
  chain: 'BitBadges',
}

Ownership Times

Querying ownership is only supported for the current time for Ethereum assets (according to Moralis API).

For BitBadges, we support checking ownership time via their time-based balances feature. Note this is an ownership rights feature, it queries if the user has ownership rights for time XYZ currently, not that they had rights at time XYZ for time XYZ. See here.

To actually query if they owned at the current time, you must query the blockchain state at that time or provide a snapshot of it at that time.

Snapshots

You can provide snapshots for BitBadges badges via the verifyChallenge options. Snapshot maps are expected to be in the form of OffChainBalancesMap<NumberType>. See https://bafybeiejae7ylsndxcpxfrfctdlzh2my7ts5hk6fxhxverib7vei3wjn4a.ipfs.dweb.link/.