Chainsauce 💃

General-purpose Ethereum blockchain indexing library.

---

Chainsauce is a general-purpose Ethereum indexer that sources contract events from a JSON-RPC endpoint.

Installation

1$ npm install boudra/chainsauce#main

Basic usage

1import { createIndexer, createHttpRpcClient } from "chainsauce";
2import { erc20ABI } from "./erc20ABI.ts";
3
4// -- Define contracts
5const MyContracts = {
6  ERC20: erc20ABI,
7};
8
9// -- Create an indexer:
10
11const indexer = createIndexer({
12  chain: {
13    id: 1,
14    rpcClient: createHttpRpcClient({
15      url: "https://mainnet.infura.io/v3/...",
16    }),
17  },
18  contracts: MyContracts,
19});
20
21// -- Attach event listeners:
22
23// subscribe to a specific event
24indexer.on("ERC20:Approval", async ({ event }) => {
25  console.log("Approval event:", event.params);
26});
27
28// subscribe to all events
29indexer.on("event", async ({ event }) => {
30  console.log("Event:", event.params);
31});
32
33// -- Subscribe to deployed contracts:
34
35indexer.subscribeToContract({
36  contract: "ERC20",
37  address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
38
39  // optional
40  fromBlock: 18363594n,
41  toBlock: "latest"
42});
43
44// -- One off indexing:
45
46// one off indexing, this will resolve when finished or reject if any error happens
47await indexer.indexToBlock("latest");
48
49// -- Continous indexing:
50
51// indexes to the latest block and watches the chain for new events
52// until stopped with `indexer.stop()`
53// errors will be emitted and will not stop indexing
54indexer.on("error", (error) => {
55   console.error("whoops", error);
56});
57indexer.watch();

Event handler types

Event handlers should be automatically inferred when used like this:

1indexer.on("ERC20:Approval", async ({ event, context }) => {
2  // event is inferred to be an Approval event
3  // context is inferred to be the context passed into `createIndexer`
4});

But if you need to split out event handler function to other files, you can type them like this;

1import { Indexer as ChainsauceIndexer } from "chainsauce";
2
3type MyContext = {
4  db: DatabaseConnection
5};
6
7const MyContracts = {
8  ERC20: erc20ABI,
9};
10
11type Indexer = ChainsauceIndexer<typeof MyContracts, MyContext>;
12
13const indexer: Indexer = createIndexer({
14   ...
15   context: { db: new DatabaseConnection() }
16});
17
18async function handleTransfer({
19  event, context: { db }
20}: EventHandlerArgs<Indexer, "ERC20", "Transfer">) {
21  // event is a Transfer event
22  // context is a MyContext type
23}
24
25indexer.on("ERC20:Transfer", handleTransfer);

How to define ABIs

ABIs in Chainsauce are of type type Abi in abitype.

ABIs must be defined in Typescript if you want automatic typing of events and contract reads, make sure you cast ABIs as const:

1const myAbi = [
2  ...
3] as const;

Factory Contracts

You can subscribe to new deployed contracts in your event handlers by using the function subscribeToContract:

1indexer.on("FactoryContract:ContractCreated", async ({ event, context, subscribeToContract }) => {
2  subscribeToContract({
3    contract: "MyContract",
4    address: event.params.contractAddress,
5
6    // optional
7    toBlock: "latest"
8  });
9});

Caching events and contract reads

Chainsauce comes with a cache to speed up reindexing, all you have to do is pass a cache when creating the indexer.

Currently only a SQLite version is available, but other options are planned.

1import { createIndexer, createSqliteCache } from "chainsauce";
2
3const indexer = createIndexer({
4  cache: createSqliteCache("./chainsauce.db"),
5});

Complete examples

• https://github.com/gitcoinco/grants-stack-indexer