Skip to content

A collection of utilities and helpers to support the development of subgraphs

License

Notifications You must be signed in to change notification settings

protofire/subgraph-toolkit

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

26 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Subgraph Toolkit

A Swiss Army knife for building subgraphs on The Graph Protocol

NPM Package License: GPL v3 Code Style: prettier


Content

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 1018

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 1018
units. RAY
The BigDecimal representing 1027
units. RAD
The BigDecimal representing 1045

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:

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.