Subgraph Deployment with Goldsky

Documentation Index

For AI agents, the full documentation index is at /docs/llms.txt.

This guide covers how to deploy and manage subgraphs for Mezo protocols using Goldsky’s infrastructure. Subgraphs enable efficient querying of blockchain data through GraphQL APIs.

Overview

Subgraphs provide:

• Indexed Data: Fast access to blockchain data
• GraphQL API: Flexible querying interface
• Real-time Updates: Live data synchronization
• Custom Logic: Transform and aggregate on-chain data

Repository Structure

Mezo subgraph repositories typically contain:

• schema.graphql: GraphQL schema definitions
• subgraph.yaml: Subgraph manifest
• src/: Mapping logic (AssemblyScript)
• abis/: Contract ABIs
• tests/: Unit tests

Development Setup

Prerequisites

• Node.js 18+ (check repository’s .nvmrc for exact version)
• npm or yarn package manager
• Git
• Graph CLI
• Goldsky account

Installation

1. Clone the subgraph repository:

git clone https://github.com/mezo-org/subgraphs.git
cd subgraphs

2. Install dependencies:

npm install
# or
yarn install

3. Install Graph CLI:

npm install -g @graphprotocol/graph-cli

Subgraph Development

Schema Definition

Define your data models in schema.graphql:

type Token @entity {
  id: ID!
  name: String!
  symbol: String!
  decimals: Int!
  totalSupply: BigInt!
}

type Transfer @entity {
  id: ID!
  from: Bytes!
  to: Bytes!
  amount: BigInt!
  timestamp: BigInt!
  transactionHash: Bytes!
}

Subgraph Manifest

Configure your subgraph in subgraph.yaml:

specVersion: 0.0.5
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: MUSDToken
    network: mezo-mainnet
    source:
      address: "0x..." # Contract address
      abi: MUSD
      startBlock: 0
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Token
        - Transfer
      abis:
        - name: MUSD
          file: ./abis/MUSD.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,uint256)
          handler: handleTransfer
      file: ./src/mapping.ts

Mapping Logic

Implement event handlers in src/mapping.ts:

import { Transfer as TransferEvent } from "../generated/MUSDToken/MUSD"
import { Transfer, Token } from "../generated/schema"
import { BigInt } from "@graphprotocol/graph-ts"

export function handleTransfer(event: TransferEvent): void {
  // Create transfer entity
  let transfer = new Transfer(
    event.transaction.hash.toHex() + "-" + event.logIndex.toString()
  )

  transfer.from = event.params.from
  transfer.to = event.params.to
  transfer.amount = event.params.value
  transfer.timestamp = event.block.timestamp
  transfer.transactionHash = event.transaction.hash

  transfer.save()

  // Update token entity
  let token = Token.load("1")
  if (token == null) {
    token = new Token("1")
    token.name = "Mezo USD"
    token.symbol = "MUSD"
    token.decimals = 18
    token.totalSupply = BigInt.fromI32(0)
  }

  token.save()
}

Code Generation

Generate TypeScript types from your schema:

# Generate types
graph codegen

# Build subgraph
graph build

Testing

Unit Tests

Write unit tests for your mappings:

import { describe, test, assert } from "matchstick-as/assembly/index"
import { handleTransfer } from "../src/mapping"
import { createTransferEvent } from "./utils"

describe("MUSD Transfer", () => {
  test("Should create transfer entity", () => {
    let event = createTransferEvent(
      "0xfrom",
      "0xto",
      BigInt.fromI32(1000)
    )

    handleTransfer(event)

    assert.fieldEquals(
      "Transfer",
      event.transaction.hash.toHex(),
      "amount",
      "1000"
    )
  })
})

Run tests:

# Run all tests
npm test

# Run specific test
graph test

Deployment with Goldsky

Prerequisites

1. Create Goldsky Account: Sign up at goldsky.com
2. Install Goldsky CLI:

npm install -g @goldsky/cli

3. Authenticate:

goldsky login

Deployment Process

1. Deploy Subgraph:

# Deploy to Goldsky
goldsky subgraph deploy <subgraph-name> <version>

# Example
goldsky subgraph deploy musd-subgraph 1.0.0

2. Monitor Deployment:

# Check deployment status
goldsky subgraph status <subgraph-name>

# View logs
goldsky subgraph logs <subgraph-name>

Configuration

Create a Goldsky configuration file:

{
  "version": "1",
  "name": "musd-subgraph",
  "schema": "./schema.graphql",
  "dataSources": [
    {
      "name": "MUSD",
      "network": "mezo-mainnet",
      "address": "0x...",
      "startBlock": 0
    }
  ]
}

Querying Subgraphs

GraphQL Queries

Once deployed, query your subgraph:

# Get recent transfers
{
  transfers(first: 10, orderBy: timestamp, orderDirection: desc) {
    id
    from
    to
    amount
    timestamp
    transactionHash
  }
}

# Get token information
{
  token(id: "1") {
    name
    symbol
    decimals
    totalSupply
  }
}

# Filter transfers by address
{
  transfers(where: { from: "0x..." }) {
    id
    to
    amount
    timestamp
  }
}

Client Integration

Integrate subgraph queries in your dApp:

import { request, gql } from 'graphql-request'

const endpoint = 'https://api.goldsky.com/api/public/project_...'

const query = gql`
  {
    transfers(first: 10, orderBy: timestamp, orderDirection: desc) {
      id
      from
      to
      amount
      timestamp
    }
  }
`

async function getTransfers() {
  const data = await request(endpoint, query)
  return data.transfers
}

Apollo Client Integration

import { ApolloClient, InMemoryCache, gql } from '@apollo/client'

const client = new ApolloClient({
  uri: 'https://api.goldsky.com/api/public/project_...',
  cache: new InMemoryCache()
})

const GET_TRANSFERS = gql`
  query GetTransfers {
    transfers(first: 10, orderBy: timestamp, orderDirection: desc) {
      id
      from
      to
      amount
      timestamp
    }
  }
`

client.query({ query: GET_TRANSFERS })
  .then(result => console.log(result))

Monitoring and Maintenance

Health Checks

Monitor subgraph health:

# Check sync status
goldsky subgraph status <subgraph-name>

# View sync lag
goldsky subgraph info <subgraph-name>

Updating Subgraphs

Deploy new versions:

# Deploy updated version
goldsky subgraph deploy <subgraph-name> <new-version>

# Example
goldsky subgraph deploy musd-subgraph 1.1.0

Error Handling

Common issues and solutions:

1. Sync Lag: Check RPC endpoint health
2. Failed Handlers: Review mapping logic and logs
3. Schema Mismatches: Ensure schema matches deployment

Best Practices

Schema Design

1. Entities: Use meaningful entity names
2. Relationships: Define clear entity relationships
3. Indexing: Index frequently queried fields
4. Immutability: Use immutable IDs for entities

Mapping Logic

1. Error Handling: Handle null values gracefully
2. Gas Efficiency: Minimize entity loads and saves
3. Consistency: Maintain data consistency
4. Testing: Write comprehensive unit tests

Performance

1. Start Block: Set appropriate start blocks
2. Batch Processing: Process events in batches
3. Caching: Use entity caching effectively
4. Pagination: Implement proper pagination in queries

Additional Resources

• Goldsky Documentation - Goldsky platform docs
• The Graph Documentation - Subgraph development guide
• GraphQL Documentation - GraphQL query language
• AssemblyScript Documentation - Mapping language

Note

For detailed subgraph schemas, deployment configurations, and protocol-specific mappings, refer to the individual subgraph repositories in the Mezo organization.

Support

For subgraph development support:

• Join the Mezo Discord
• Check subgraph repository issues on GitHub
• Review the FAQ
• Contact Goldsky Support