Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/protofire/subgraph-toolkit

A collection of utilities and helpers to support the development of subgraphs
https://github.com/protofire/subgraph-toolkit

ethereum subgraphs thegraphprotocol

Last synced: about 2 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/protofire/subgraph-toolkit
Owner: protofire
License: gpl-3.0
Created: 2020-05-28T12:49:35.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2022-11-10T07:18:43.000Z (about 2 years ago)
Last Synced: 2024-10-13T01:33:30.476Z (2 months ago)
Topics: ethereum, subgraphs, thegraphprotocol
Language: TypeScript
Homepage: https://thegraph.com/
Size: 99.6 KB
Stars: 52
Watchers: 11
Forks: 6
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-subgraphs - Subgraph Toolkit

README

        # Subgraph Toolkit

A Swiss Army knife for building subgraphs on [The Graph Protocol](https://thegraph.com)

[![NPM Package](https://img.shields.io/npm/v/@protofire/subgraph-toolkit)](https://www.npmjs.com/package/@protofire/subgraph-toolkit)

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

[![Code Style: prettier](https://img.shields.io/badge/Code_Style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

---

**Content**

* [Features](#features-)

* [Install](#install-)

* [Usage](#usage-)

* [Documentation](#documentation-)

* [Examples](#example-)

* [Contributing](#contributing-)

## Features ✨

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

- [x] Helper functions to convert between different types not available in the standard library

    - [x] Convert Bytes to Address

    - [x] Convert Bytes to signed and unsigned integer

    - [x] Convert BigDecimal to BigInt with a given precision

    - [x] Convert BigInt to Bytes

    - [x] Convert BigInt to BigDecimal with a given precision

- [x] Useful constants ready to use in the subgraph mappings (including numeric constants, addresses, hashes and more)

- [x] Calculate maximum and minimum of BigInt and BigDecimal values

- [x] Hex Strings helpers

- [x] Counters

- [x] Accumulators

- [ ] Helper functions to handle aggregated data [WIP]

- [ ] Utilities to manipulate tokens (ERC20/ERC721/ERC1115)

## Install 🐙

```bash

  $ 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 💡

```typescript

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](./schema.graphql) to the subgraph schema.

### Prettier configuration

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

```javascript

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

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

```

To override and/or extend the configuration:

```javascript

// 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](https://thegraph.com/explorer/subgraph/protofire/maker-protocol)

* [Curve](https://thegraph.com/explorer/subgraph/protofire/curve)

* [Nexus Mutual](https://thegraph.com/explorer/subgraph/protofire/nexus-mutual)

* [SuperRare](https://thegraph.com/explorer/subgraph/protofire/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 .