Subgraph Toolkit

A Swiss Army knife for building subgraphs on The Graph Protocol

Content

• Features
• Install
• Usage
• Documentation
• Examples
• Contributing

Features ✨

This library complements and extends the official library @graphprotocol/graph-ts with the following functionality:

• Helper functions to convert between different types not available in the standard library
  • Convert Bytes to Address
  • Convert Bytes to signed and unsigned integer
  • Convert BigDecimal to BigInt with a given precision
  • Convert BigInt to Bytes
  • Convert BigInt to BigDecimal with a given precision
• Useful constants ready to use in the subgraph mappings (including numeric constants, addresses, hashes and more)
• Calculate maximum and minimum of BigInt and BigDecimal values
• Hex Strings helpers
• Counters
• Accumulators
• Helper functions to handle aggregated data [WIP]
• Utilities to manipulate tokens (ERC20/ERC721/ERC1115)

Install 🐙

  $ yarn add @protofire/subgraph-toolkit --exact

NOTE

It's recommended installing a specific version of this library since the API in early versions is subject to change without previous notice.

Usage 💡

import { integer, decimal, DEFAULT_DECIMALS, ZERO_ADDRESS } from '@protofire/subgraph-toolkit'

// ...

export function handleTransfer(event: Transfer): void {
  // ...
  
  if (event.params._to.toHexString == ZERO_ADDRESS) {
    let amount = decimal.max(
      decimal.ZERO,
      decimal.fromBigInt(event.params._value, DEFAULT_DECIMALS)
    )

    totalBurned += amount

    burnCount = integer.increment(burnCount)
  }
  
  // ...
}

// ...

Counters and accumulators

To use metrics module you need to append the content of schema.graphql to the subgraph schema.

Prettier configuration

This package also provides an opinionated Prettier configuration file. To apply this configuration:

// prettier.config.js or .prettierrc.js

module.exports = require('@protofire/subgraph-toolkit/prettier.config.js')

To override and/or extend the configuration:

// prettier.config.js or .prettierrc.js

module.exports = {
  ...require('@protofire/subgraph-toolkit/prettier.config.js'),

  printWidth: 120,

  overrides: [
    {
      files: '*.json',
      options: {
        printWidth: 80,
      },
    },
  ],
}

Documentation 📄

Constants

ADDRESS_ZERO

The address zero, which is 20 bytes (40 nibbles) of zero. Aliases: GENESIS_ADDRESS, ZERO_ADDRESS

HASH_ZERO

The hash zero, which is 32 bytes (64 nibbles) of zero. Alias: ZERO_HASH

MAX_UINT

The hex string representing the maximum `uint256` value. Alias: MAX_UINT_256

Integers

integer. NEGATIVE_ONE

The BigInt representing -1

integer. ZERO

The BigInt representing 0

integer. ONE

The BigInt representing 1

integer. TWO

The BigInt representing 2

integer. ONE_THOUSAND

The BigInt representing 1000

integer. WEI_PER_ETHER

The BigInt representing 10¹⁸

Decimals

decimal. NEGATIVE_ONE

The BigDecimal representing -1

decimal. ZERO

The BigDecimal representing 0

decimal. ONE

The BigDecimal representing 1

decimal. TWO

The BigDecimal representing 2

Units

MakerDAO

units. WAD

The BigDecimal representing 10¹⁸

units. RAY

The BigDecimal representing 10²⁷

units. RAD

The BigDecimal representing 10⁴⁵

Helper functions

Addresses

address. isZeroAddress(address: Address) → Boolean

Checks if a given address is the zero address

Byte Manipulation

bytes. toAddress(address: Bytes) → Address

Checks if a given address is the zero address (0x0)

bytes. toSignedInt(value: Bytes, bigEndian: Boolean = true) → BigInt

Converts Bytes to a signed BigInt using a given endianness

bytes. toUnsignedInt(value: Bytes, bigEndian: Boolean = true) → BigInt

Converts Bytes to a unsigned BigInt using a given endianness

bytes. hexZeroPad(value: Bytes, length: i32 → String

Returns a hex string padded with zeros (on the left) to length bytes (each byte is two nibbles)

Integer

integer. fromBigInt(value: BigInt, decimals: i32 = 18) → BigDecimal

Converts a BigInt to a BigDecimal including a given number of decimals (by default, 18 decimals)

Factory methods

integer. fromNumber(value: i32) → BigInt

Converts a integer number to a BigInt

integer. fromString(value: String) → BigInt

Parses a string as a BigInt

Converters

integer. toBytes(value: BigInt) → Bytes

Converts a BigInt to a raw Bytes

Other helpers

integer. decrement(value: BigInt, amount: BigInt = 1) → BigInt

Decrements a BigInt by a given amount and returns the new value (by default, decrements by 1)

integer. increment(value: BigInt, amount: BigInt = 1) → BigInt

Increments a BigInt by a given amount and returns the new value (by default, increments by 1)

integer. min(a: BigInt, b: BigInt) → BigInt

Returns the smallest of the given numbers

integer. max(a: BigInt, b: BigInt) → BigInt

Returns the largest of the given numbers

Decimal

decimal. fromBigInt(value: BigInt, decimals: i32 = 18) → BigDecimal

Converts a BigInt to a BigDecimal including a given number of decimals (by default, 18 decimals)

Factory methods

decimal. fromNumber(value: f64) → BigDecimal

Converts a float number to a BigDecimal

decimal. fromString(value: String) → BigDecimal

Parses a string as a BigDecimal

Converters

decimal. toBigInt(value: BigDecimal, decimals: u8 = 18) → BigInt

Converts a BigDecimal to a BigInt using a given number of decimals (by default, 18 decimals)

Other helpers

decimal. getPrecision(decimals: u8 = 18) → BigInt

Returns a BigInt representing a unit of a fixed point decimal with a given number of decimals (by default, 18 decimals)

decimal. min(a: BigDecimal, b: BigDecimal) → BigDecimal

Returns the smallest of the given numbers

decimal. max(a: BigDecimal, b: BigDecimal) → BigDecimal

Returns the largest of the given numbers

Units

MakerDAO

units. fromRad(value: BigInt) → BigDecimal

Reads a BigInt as a fixed point decimal with 18 decimals (used for basic quantities, e.g. balances)

units. fromRay(value: BigInt) → BigDecimal

Reads a BigInt as a fixed point decimal with 27 decimals (for precise quantites, e.g. ratios)

units. fromWad(value: BigInt) → BigDecimal

Reads a BigInt as a fixed point decimal with 45 decimals (result of integer multiplication with a `wad` and a `ray)

units. toRad(value: BigDecimal) → BigInt

Converts a BigDecimal to a BigInt representing a fixed point decimal with 18 decimals (used for basic quantities, e.g. balances)

units. toRay(value: BigDecimal) → BigInt

Converts a BigDecimal to a BigInt representing a fixed point decimal with 27 decimals (for precise quantites, e.g. ratios)

units. toWad(value: BigDecimal) → BigInt

Converts a BigDecimal to a BigInt representing a fixed point decimal with 45 decimals (result of integer multiplication with a WAD and a RAY)

Examples 🖍

The following subgraphs are using this library:

• Maker Protocol
• Curve
• Nexus Mutual
• SuperRare

Contributing 🍰

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to this project!

License ⚖️

Copyright © 2020 Protofire.io and contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses.