### Example Typegen Command

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

Example of how to start the typegen process with ABI and output paths.

```bash
squid-ink-typegen --abi erc20.json --output src/erc20.ts
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Install all project dependencies using Rush. This command should be run after cloning the repository and installing Rush.

```bash
rush install
```

--------------------------------

### Install Dependencies and Run Indexer

Source: https://github.com/subsquid/squid-sdk/blob/master/test/solana-example/README.md

Commands to install dependencies, compile the project, set up the database, apply migrations, and run the indexer. Ensure Node.js v20+ and Docker are installed.

```bash
npm ci

npx tsc

docker compose up -d

npx squid-typeorm-migration apply

node -r dotenv/config lib/main.js
```

--------------------------------

### Install @subsquid/ink-abi and @subsquid/ink-typegen

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

Install the necessary packages for generating and using ink! contract types.

```bash
npm i @subsquid/ink-abi
npm i @subsquid/ink-typegen --save-dev
```

--------------------------------

### Install @subsquid/evm-typegen

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Install the evm-typegen tool globally using npm.

```bash
npm i -g @subsquid/evm-typegen
```

--------------------------------

### Install Rush

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Install the Rush build tool globally using npm. This is a prerequisite for managing the Subsquid monorepo.

```bash
npm install -g @microsoft/rush
```

--------------------------------

### GraphQL Query and Subscription Examples

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Demonstrates auto-generated GraphQL queries for fetching data with filtering, ordering, and limiting, as well as a subscription example for real-time updates. Includes a query for processor status.

```graphql
# Auto-generated queries based on your schema
query {
    transfers(
        where: {from_eq: "0x1234...", amount_gt: "1000000"}
        orderBy: timestamp_DESC
        limit: 100
    ) {
        id
        from
        to
        amount
        timestamp
    }

    # Processor status query
    squidStatus {
        height
        hash
        finalizedHeight
        finalizedHash
    }
}

# Subscriptions for real-time updates
subscription {
    transfers(where: {to_eq: "0x..."}) {
        id
        amount
    }
}
```

--------------------------------

### Install and List Commands for TypeORM Migration

Source: https://github.com/subsquid/squid-sdk/blob/master/typeorm/typeorm-migration/README.md

Install the package using npm and then use npx to list available commands for managing TypeORM migrations.

```bash
# 1. Install
npm i @subsquid/typeorm-migration
```

```bash
# 2. List available commands
npx squid-typeorm-migration --help
```

--------------------------------

### Usage Example for Contract State Calls

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

Example demonstrating how to instantiate the generated Contract class and call a state-querying method like total_supply.

```typescript
// Usage example:
let contract = new Contract(ctx, contractAddress)
let totalSupply = await contract.total_supply()
```

--------------------------------

### Navigate and Run Local Services for Gear NFT Test

Source: https://github.com/subsquid/squid-sdk/blob/master/test/gear-nft/README.md

After building, navigate to the test directory and start the necessary services using make commands. The 'serve' command should be run in a separate terminal.

```bash
cd test/gear-nft/

make up
make processor
make serve  # in separated terminal
```

--------------------------------

### Run All Tests

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-rpc/test/README.md

Execute all tests in the suite. Ensure you have the necessary dependencies installed via npm.

```bash
npm test
```

--------------------------------

### Run Rush Command with Starter Script

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Execute a Rush command using the provided starter script. This script can be used as an alternative to a globally installed Rush CLI.

```bash
node common/scripts/install-run-rush.js <regular rush command>
```

--------------------------------

### Install @subsquid/evm-objects and @subsquid/evm-stream

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-objects/README.md

Install the necessary packages for using the augmented EVM data model with the EVM stream processor.

```bash
npm install @subsquid/evm-objects @subsquid/evm-stream
```

--------------------------------

### Install and Run typeorm-codegen

Source: https://github.com/subsquid/squid-sdk/blob/master/typeorm/typeorm-codegen/README.md

Install the package as a development dependency and then run the codegen command using npx. This command has no options and follows squid project conventions.

```bash
# 1. Install
npm i @subsquid/typeorm-codegen --save-dev
```

```bash
#2. Run
npx squid-typeorm-codegen
```

--------------------------------

### Run Unit Tests

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Execute the unit tests for the project. Ensure Docker is installed and running.

```bash
# Run unit tests
rush test
```

--------------------------------

### Usage Example for Decoding Events

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

Example demonstrating how to use the generated decodeEvent function and type guard for specific event types.

```typescript
// Usage example:
let event = decodeEvent(item.event.args.data)
if (event.__kind === 'Transfer') {
    // event is of type `Event_Transfer`
}
```

--------------------------------

### Scaffold a Squid Project with sqd init

Source: https://github.com/subsquid/squid-sdk/blob/master/README.md

Use the squid CLI to initialize a new squid project. This command is the starting point for creating new data indexing projects with the Squid SDK.

```bash
sqd init
```

--------------------------------

### Usage Example

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-objects/README.md

Demonstrates how to use `augmentBlock` within the `run` function from `@subsquid/evm-stream` to process augmented EVM blocks and access related entities like transactions, logs, and traces.

```APIDOC
## Usage Example

### Description
This example shows how to integrate `@subsquid/evm-objects` with `@subsquid/evm-stream` to process EVM data.

### Method
```typescript
run, augmentBlock
```

### Endpoint
None (This is a code example, not an API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import {augmentBlock} from '@subsquid/evm-objects'
import {run} from '@subsquid/evm-stream'

run({
    // ... stream configuration
}, async (streamBlocks) => {
    for (let block of streamBlocks) {
        // Augment the block with relationships
        let augmented = augmentBlock(block)
        
        // Access transactions with their logs
        for (let tx of augmented.transactions) {
            console.log(`Transaction ${tx.id} has ${tx.logs.length} logs`)
            
            // Access logs
            for (let log of tx.logs) {
                console.log(`Log ${log.id} belongs to tx ${log.getTransaction().id}`)
            }
            
            // Access traces with parent-child relationships
            for (let trace of tx.traces) {
                console.log(`Trace ${trace.id} has ${trace.children.length} children`)
                if (trace.parent) {
                    console.log(`Parent trace: ${trace.parent.id}`)
                }
            }
        }
    }
})
```

### Response
#### Success Response (200)
None (This is a code example)

#### Response Example
None
```

--------------------------------

### JSON Output Example

Source: https://github.com/subsquid/squid-sdk/blob/master/util/logger/README.md

Example of structured log output in JSON format, typically used when stderr is not connected to a terminal.

```json
{"level":2,"time":1669387525765,"ns":"sqd:demo","msg":"message with severity info"}
{"level":2,"time":1669387525766,"ns":"sqd:demo","msg":"message and some additional attributes","foo":1,"bar":2}
{"level":2,"time":1669387525766,"ns":"sqd:demo","a":1,"b":2,"c":3,"array":[4,5,6],"obj":{"foo":"foo","bar":"bar"}}
{"level":3,"time":1669387525766,"ns":"sqd:demo","err":{"stack":"Error: Some error occured\n    at Object.<anonymous> (/Users/eldar/dev/squid/util/logger/lib/demo.js:11:10)\n    at Module._compile (node:internal/modules/cjs/loader:1159:14)\n    at Module._extensions..js (node:internal/modules/cjs/loader:1213:10)\n    at Module.load (node:internal/modules/cjs/loader:1037:32)\n    at Module._load (node:internal/modules/cjs/loader:878:12)\n    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)\n    at node:internal/main/run_main_module:23:47"}}
{"level":4,"time":1669387525766,"ns":"sqd:demo","msg":"weird","err":{"stack":"Error: Another error\n    at Object.<anonymous> (/Users/eldar/dev/squid/util/logger/lib/demo.js:13:18)\n    at Module._compile (node:internal/modules/cjs/loader:1159:14)\n    at Module._extensions..js (node:internal/modules/cjs/loader:1213:10)\n    at Module.load (node:internal/modules/cjs/loader:1037:32)\n    at Module._load (node:internal/modules/cjs/loader:878:12)\n    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)\n    at node:internal/main/run_main_module:23:47"},"a":1,"b":2}
```

--------------------------------

### Configure and Use EVM Block Data Source

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-stream/README.md

Set up a data source to stream EVM block data, specifying which logs, transactions, traces, or state diffs to include. This example demonstrates how to configure filters and relations for each data type and then iterate over the streamed data.

```typescript
import {DataSourceBuilder} from '@subsquid/evm-stream'

const dataSource = new DataSourceBuilder()
    .setPortal('https://portal.sqd.dev/datasets/ethereum-mainnet')
    .setFields({
        log: {
            topics: true,
            data: true,
        },
        transaction: {
            hash: true,
            input: true,
        }
    })
    .addLog({
        where: {
            address: ['0x...'],
            topic0: ['0x...']
        },
        include: {
            transaction: true
        }
    })
    .addTransaction({
        where: {
            to: ['0x...'],
            sighash: ['0x...']
        },
        include: {
            logs: true,
            traces: true
        }
    })
    .addTrace({
        where: {
            type: ['call', 'create'],
            callTo: ['0x...']
        },
        include: {
            transaction: true
        }
    })
    .addStateDiff({
        where: {
            address: ['0x...'],
            kind: ['+', '*']
        },
        include: {
            transaction: true
        }
    })
    .build()

// Use the data source
for await (let batch of dataSource.getStream()) {
    for (let block of batch.blocks) {
        // Process blocks
        console.log(block.header.height)
        for (let log of block.logs) {
            console.log(log.address, log.topics)
        }
    }
}
```

--------------------------------

### GraphQL Server Setup and Configuration

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Sets up an Apollo-based GraphQL API server that automatically generates queries from your TypeORM schema. Configure port, query timeouts, complexity limits, and subscription settings.

```typescript
import {Server} from '@subsquid/graphql-server'

// Start server with default options
const server = new Server({
    port: 4000,
    sqlStatementTimeout: 60000,  // Query timeout in ms
    maxRootFields: 10,  // Limit query complexity
    maxResponseNodes: 10000,  // Limit response size
    subscriptions: true,  // Enable GraphQL subscriptions
    subscriptionPollInterval: 1000,  // Polling interval for subscriptions
})

server.start().then(listening => {
    console.log(`GraphQL server running at http://localhost:${listening.port}/graphql`)
})
```

--------------------------------

### Get SS58 Registry Information

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ss58/README.md

Use `ss58.registry.get()` to retrieve network details by name or prefix. This function requires the SS58 registry to be available.

```typescript
import * as ss58 from "@subsquid/ss58"

ss58.registry.get('kusama') // => {prefix: 2, network: 'kusama', ...}
ss58.registry.get(2) // => {prefix: 2, network: 'kusama', ...}
```

--------------------------------

### Run Tests Requiring Git LFS Files

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Run tests that depend on Git LFS files. This requires Git LFS to be properly installed and configured.

```bash
# Run tests requiring git-lfs files
rush data-test
```

--------------------------------

### Generated ERC20 Typescript Definitions

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Example of generated TypeScript code for ERC20 events and functions, including Transfer, Approval, balanceOf, and transfer.

```typescript
import {event, fun, viewFun, indexed} from '@subsquid/evm-abi'
import {address, uint256} from '@subsquid/evm-codec'

export const events = {
    Transfer: event(
        '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
        'Transfer(address,address,uint256)',
        {from: indexed(address), to: indexed(address), value: uint256}
    ),
    Approval: event(
        '0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925',
        'Approval(address,address,uint256)',
        {owner: indexed(address), spender: indexed(address), value: uint256}
    )
}

export const functions = {
    balanceOf: viewFun('0x70a08231', 'balanceOf(address)', {account: address}, uint256),
    transfer: fun('0xa9059cbb', 'transfer(address,uint256)', {to: address, amount: uint256}, bool)
}
```

--------------------------------

### TypeORM Database and Store Operations

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Integrates with PostgreSQL for data persistence, managing processor state and supporting hot blocks. Provides a Store API for CRUD operations like insert, upsert, find, get, remove, and count.

```typescript
import {TypeormDatabase, Store} from '@subsquid/typeorm-store'
import {Entity, Column, PrimaryColumn} from 'typeorm'

// Define entity (generated by squid-typeorm-codegen)
@Entity()
export class Transfer {
    @PrimaryColumn()
    id!: string

    @Column()
    from!: string

    @Column()
    to!: string

    @Column('numeric', {transformer: bigintTransformer})
    amount!: bigint
}

// Initialize database with options
const database = new TypeormDatabase({
    supportHotBlocks: true,  // Enable unfinalized block tracking
    isolationLevel: 'SERIALIZABLE',  // Transaction isolation
    stateSchema: 'squid_processor'  // Schema for state tables
})

// Store API usage in handler
processor.run(database, async ctx => {
    // Batch insert (most efficient)
    let transfers: Transfer[] = []
    for (let block of ctx.blocks) {
        for (let log of block.logs) {
            transfers.push(new Transfer({
                id: log.id,
                from: '0x...',
                to: '0x...',
                amount: 1000n
            }))
        }
    }
    await ctx.store.insert(transfers)

    // Upsert (insert or update)
    await ctx.store.upsert(new Transfer({id: 'abc', ...}))

    // Find entities
    let existing = await ctx.store.find(Transfer, {
        where: {from: '0x1234...'},
        take: 100,
        order: {amount: 'DESC'}
    })

    // Get by ID
    let transfer = await ctx.store.get(Transfer, 'some-id')

    // Delete
    await ctx.store.remove(Transfer, ['id1', 'id2'])

    // Count
    let count = await ctx.store.countBy(Transfer, {from: '0x...'})
```

--------------------------------

### Clone Subsquid Repo Skipping LFS

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Clone the Subsquid repository while skipping the download of large Git LFS files. This is useful for initial setup when LFS files are not immediately needed.

```bash
GIT_LFS_SKIP_SMUDGE=1 git clone git@github.com:subsquid/squid-sdk.git
```

--------------------------------

### Sample commands.json Configuration

Source: https://github.com/subsquid/squid-sdk/blob/master/util/commands/README.md

This JSON5 file demonstrates the structure and features of `commands.json`, including comments, command definitions with descriptions, dependencies, working directories, environment variables, and cross-platform glob expansion.

```json5
{
  // comments are ok
  "$schema": "https://subsquid.io/schemas/commands.json",
  "commands": {
    "clean": {
      "description": "delete all build artifacts",
      "cmd": ["rm", "-rf", "lib"]
    },
    "build": {
      "description": "build the project",
      "deps": ["clean"], // commands to execute before
      "cmd": ["tsc"]
    },
    "typegen": {
      "hidden": true, // Don't show in the overview listing
      "workdir": "abi", // change working dir
      "command": [
        "squid-evm-typegen", // node_modules/.bin is in the PATH
        "../src/abi",
        {"glob": "*.json"} // cross-platform glob expansion
      ],
      "env": { // additional environment variables
        "DEBUG": "*"
      }
    }
  }
}
```

--------------------------------

### Initialize and Use Binary Heap

Source: https://github.com/subsquid/squid-sdk/blob/master/util/util-internal-binary-heap/README.md

Demonstrates how to initialize a binary heap with a custom comparison function and perform basic operations like push, pop, peek, and size. The init method can be used to populate the heap from an array.

```typescript
import {Heap} from "@subsquid/util-internal-binary-heap"

const h = new Heap(function compare(a, b) {
  return a - b
})

h.push(5)
h.push(0)
h.push(10)

h.pop() // => 0
h.pop() // => 5
h.pop() // => 10

h.init([5, 2, 3, 1, 4]) // will modify array in-place and use it as a storage
h.pop() // => 1

h.peek() // => 2
h.size() // => 4

h.resort() // When you have mutable objects,
           // call this to restore heap property after changes
```

--------------------------------

### Run OpenReader

Source: https://github.com/subsquid/squid-sdk/blob/master/graphql/openreader/README.md

Execute OpenReader by providing the path to your GraphQL schema file. Database connection and server port are configured via environment variables.

```bash
openreader schema.graphql
```

--------------------------------

### List Defined Commands with squid-commands

Source: https://github.com/subsquid/squid-sdk/blob/master/util/commands/README.md

Execute this command in your project's root directory to list all available commands defined in `commands.json`. No arguments are needed.

```shell
squid-commands
```

--------------------------------

### Subscribe to Solana Whirlpool Swaps

Source: https://github.com/subsquid/squid-sdk/blob/master/solana/solana-spray/README.md

Use SprayClient to subscribe to a stream of Whirlpool swap instructions on Solana. Ensure the program ID and discriminator are correctly specified for filtering.

```typescript
import {SprayClient} from '@subsquid/spray'

const client = new SprayClient('wss://...')

const stream = client.subscribe({
    query: { // Select all Whirlpool swaps
        instructions: [
            {
                where: {
                    programId: ['whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc'],
                    discriminator: ['0xf8c69e91e17587c8'],
                    isCommitted: true
                },
                include: {
                    innerInstructions: true,
                    transaction: true,
                }
            }
        ]
    }
})

for await (const batch of stream) {
    for (const msg of batch) {
        console.log(msg)
    }
}
```

--------------------------------

### Update and Build Squid SDK Project

Source: https://github.com/subsquid/squid-sdk/blob/master/test/gear-nft/README.md

Run these commands to update project dependencies and build the project. Ensure you are in the project root directory.

```bash
rush update
rush build
```

--------------------------------

### Build the Project

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Build the entire Subsquid project using Rush. This command compiles all packages within the monorepo.

```bash
rush build
```

--------------------------------

### Format Code with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Format the code according to the project's style guidelines using Biome. This command only reformats the code.

```bash
# Format
rush format
```

--------------------------------

### TypeORM Migration Commands

Source: https://github.com/subsquid/squid-sdk/blob/master/typeorm/typeorm-migration/README.md

Available commands for managing TypeORM migrations: apply, create, generate, and revert.

```bash
apply           apply pending migrations
```

```bash
create          create template file for a new migration
```

```bash
generate        analyze database state and generate migration to match the target schema
```

```bash
revert          revert the last applied migration
```

--------------------------------

### OpenReader Environment Variables

Source: https://github.com/subsquid/squid-sdk/blob/master/graphql/openreader/README.md

Configure database connection and server port using these environment variables. Ensure all required variables are set for OpenReader to function correctly.

```env
DB_NAME
DB_USER
DB_PASS
DB_HOST
DB_PORT
GRAPHQL_SERVER_PORT
```

--------------------------------

### Generate Change Files with rush change

Source: https://github.com/subsquid/squid-sdk/blob/master/README.md

After making changes and committing them, run this command to document your modifications. Follow the prompts to select the change type and provide a description from a user's perspective.

```bash
rush change -b origin/master
```

--------------------------------

### Lint and Format Code with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Run both linting and formatting checks and fixes using Biome in a single command. This is a convenient way to ensure code quality.

```bash
# Lint + format together
rush biome
```

--------------------------------

### Capture Test Fixtures from Live RPC

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-rpc/test/README.md

Capture new test fixtures from a live RPC endpoint. This command requires specifying the chain, a block number, and the RPC URL. Use --with-receipts to include transaction receipts.

```bash
npm run capture-fixture -- \
  --chain ethereum \
  --block 18000000 \
  --rpc-url https://ethereum-rpc.publicnode.com \
  --with-receipts
```

--------------------------------

### Configure Solana Data Source

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Set up a Solana stream data source for indexing Solana blockchain data. Configure the portal, block range, fields, and filter instructions by program ID and discriminator.

```typescript
import {run} from '@subsquid/batch-processor'
import {augmentBlock} from '@subsquid/solana-objects'
import {DataSourceBuilder} from '@subsquid/solana-stream'
import {TypeormDatabase} from '@subsquid/typeorm-store'
import * as whirlpool from './abi/whirlpool'
import * as tokenProgram from './abi/token-program'

const dataSource = new DataSourceBuilder()
    .setPortal({url: 'https://portal.sqd.dev/datasets/solana-mainnet'})
    // Block ranges use heights, not slots
    .setBlockRange({from: 279_671_300})
    .setFields({
        block: {timestamp: true},
        transaction: {signatures: true},
        instruction: {programId: true, accounts: true, data: true},
        tokenBalance: {preMint: true, postMint: true, preAmount: true, postAmount: true}
    })
    // Filter instructions by program and discriminator
    .addInstruction({
        where: {
            programId: [whirlpool.programId],
            d8: [whirlpool.instructions.swap.d8],  // First 8 bytes discriminator
            isCommitted: true
        },
        include: {
            innerInstructions: true,
            transaction: true,
            transactionTokenBalances: true
        }
    })
    .build()

run(dataSource, new TypeormDatabase(), async ctx => {
    let blocks = ctx.blocks.map(augmentBlock)
    for (let block of blocks) {
        for (let ins of block.instructions) {
            if (ins.programId === whirlpool.programId) {
                // Access related data through augmented objects
                let tx = ins.getTransaction()
                let signature = tx.signatures[0]

                // Decode inner instructions (token transfers)
                let srcTransfer = tokenProgram.transfer.decode(ins.inner[0])
                let destTransfer = tokenProgram.transfer.decode(ins.inner[1])

                console.log(`Swap in tx ${signature}`)
            }
        }
    }
})
```

--------------------------------

### Basic Logger Usage

Source: https://github.com/subsquid/squid-sdk/blob/master/util/logger/README.md

Import and create a logger instance with a namespace. Use log methods like info and debug to log messages and attributes.

```typescript
import {createLogger} from "@subsquid/logger"

const log = createLogger('sqd:demo')

log.info('message with severity info')
log.debug('message with severity debug')

log.info({foo: 1, bar: 2}, 'message and some additional attributes')

// info message consisting only of attributes
log.info({a: 1, b: 2, c: 3, array: [4, 5], obj: {foo: 'foo', bar: "bar"}})

// pass an Error object inplace of attributes
log.warn(new Error('Some error occurred'))

// Error together with some other attributes and message
log.error({err: new Error('Another error'), a: 1, b: 2}, 'weird')

// create a child logger instance with namespace `sqd:demo:sql` 
// and `req: 1` attribute attached to every log record
const sqlLog = log.child('sql', {req: 1})
sqlLog.debug('connecting to database')
sqlLog.debug({sql: 'SELECT max(id) FROM status'})
```

--------------------------------

### Configure Substrate Batch Processor

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Set up a SubstrateBatchProcessor to index events from Substrate-based chains. Configure the gateway, RPC endpoint, fields to fetch, block range, and specific events or contract events to subscribe to.

```typescript
import {
    SubstrateBatchProcessor
} from '@subsquid/substrate-processor'
import {TypeormDatabase} from '@subsquid/typeorm-store'
import * as ss58 from '@subsquid/ss58'
import {events} from './types'

const processor = new SubstrateBatchProcessor()
    // Set Subsquid Network Gateway
    .setGateway('https://v2.archive.subsquid.io/network/kusama')
    // Set chain RPC endpoint (required for Substrate)
    .setRpcEndpoint('wss://kusama-rpc.polkadot.io')
    // Configure fields
    .setFields({
        block: {timestamp: true},
        event: {args: true}
    })
    // Set block range
    .setBlockRange({from: 19_666_100})
    // Subscribe to balance transfer events
    .addEvent({
        name: ['Balances.Transfer']
    })
    // Subscribe to ink! contract events
    .addContractsContractEmitted({
        contractAddress: ['0x10f48492ccc953b2948bc2bd027d854a73d08ad3744663bc433fd8ea9d845c8e']
    })

processor.run(new TypeormDatabase(), async ctx => {
    for (let block of ctx.blocks) {
        for (let event of block.events) {
            if (event.name === 'Balances.Transfer') {
                // Decode based on runtime version
                let rec = events.balances.transfer.v9130.decode(event)
                let from = ss58.codec('kusama').encode(rec.from)
                let to = ss58.codec('kusama').encode(rec.to)
                console.log(`Transfer: ${from} -> ${to}: ${rec.amount}`)
            }
        }
    }
})
```

--------------------------------

### Run End-to-End Test Suite

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Execute the end-to-end test suite for the project. This typically involves testing the full application flow.

```bash
# Run end to end test suite
rush e2e
```

--------------------------------

### Run Specific Test Files

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-rpc/test/README.md

Execute specific test files within the suite. Use these commands to target particular functionalities like verification, chain utilities, or RPC interactions.

```bash
npm run test:verification
```

```bash
npm run test:chain-utils
```

```bash
npm run test:rpc
```

--------------------------------

### Typegen Command Line Options

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

Options available when running the squid-ink-typegen command.

```bash
Options:
  --abi <path>     path to a JSON metadata file
  --output <path>  path for output typescript file
  -h, --help       display help for command
```

--------------------------------

### Execute Command from Any Project Directory

Source: https://github.com/subsquid/squid-sdk/blob/master/util/commands/README.md

You can execute `squid-commands` from any subdirectory within your project. The tool correctly resolves commands relative to the project root.

```shell
cd child/
squid-commands build
```

--------------------------------

### Configure EVM Stream with DataSourceBuilder

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Create EVM data sources using the DataSourceBuilder for the Subsquid Network Portal. This offers a cleaner interface than the legacy processor. Configure portal endpoint, block range, fields, and log filters.

```typescript
import {run} from '@subsquid/batch-processor'
import {augmentBlock} from '@subsquid/evm-objects'
import {DataSourceBuilder} from '@subsquid/evm-stream'
import {TypeormDatabase} from '@subsquid/typeorm-store'
import * as erc20 from './abi/erc20'

const CONTRACT = '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9'.toLowerCase()

const dataSource = new DataSourceBuilder()
    // Set Subsquid Network Portal endpoint
    .setPortal('https://portal.sqd.dev/datasets/arbitrum-one')
    // Limit block range
    .setBlockRange({from: 190000000})
    // Configure fields to fetch
    .setFields({
        block: {timestamp: true, size: true},
        log: {transactionHash: true, address: true, topics: true, data: true}
    })
    // Add log filter using 'where' clause
    .addLog({
        where: {
            address: [CONTRACT],
            topic0: [erc20.events.Transfer.topic]
        }
    })
    .build()

// Run the processor
run(dataSource, new TypeormDatabase({supportHotBlocks: true}), async ctx => {
    for (let block of ctx.blocks) {
        let augmented = augmentBlock(block)
        for (let log of augmented.logs) {
            if (log.address === CONTRACT && erc20.events.Transfer.is(log)) {
                let {from, to, value} = erc20.events.Transfer.decode(log)
                console.log(`Transfer: ${from} -> ${to}: ${value}`)
            }
        }
    }
})
```

--------------------------------

### Run Batch Processor with @subsquid/batch-processor

Source: https://context7.com/subsquid/squid-sdk/llms.txt

The generic entry point for connecting data sources with a database and handler. It manages the processing loop, handles forks, and provides metrics. Configure a data source, database, and an async handler function. Optionally, configure a custom Prometheus server for metrics.

```typescript
import {run, PrometheusServer} from '@subsquid/batch-processor'
import {DataSource} from '@subsquid/evm-stream'  // or solana-stream, etc.
import {TypeormDatabase} from '@subsquid/typeorm-store'

const dataSource = new DataSourceBuilder()
    .setPortal('https://portal.sqd.dev/datasets/ethereum-mainnet')
    .addLog({where: {topic0: ['0x...']}})
    .build()

const database = new TypeormDatabase({supportHotBlocks: true})

// Optional: custom Prometheus server
const prometheus = new PrometheusServer()
prometheus.setPort(3000)

run(
    dataSource,
    database,
    async ctx => {
        // ctx.blocks - array of blocks in this batch
        // ctx.store - database store API
        // ctx.isHead - true if we've reached chain head

        console.log(`Processing ${ctx.blocks.length} blocks`)
        console.log(`Latest: ${ctx.blocks.at(-1)?.header.number}`)
        console.log(`At head: ${ctx.isHead}`)

        // Process and persist data
        for (let block of ctx.blocks) {
            // ... processing logic
        }

        // Return template mutations for dynamic data sources
        return {
            templates: [
                {type: 'add', key: 'erc20', value: '0xnewcontract...', blockNumber: 123}
            ]
        }
    },
    {prometheus}  // Optional run options
)
```

--------------------------------

### Create and Commit a Change File

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Generate and commit a change file using Rush. This file documents modifications made to the project and is used for versioning and changelog generation.

```bash
# 3. Create and commit a change file describing your modifications
rush change -b <the target branch you are basing your changes on>
git add common/changes
git commit -m "changes"
```

--------------------------------

### Generate Type Definitions from HTTP URL

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Generate TypeScript definitions by providing an HTTP URL to a contract's ABI file. The output directory and URL are required arguments.

```bash
squid-evm-typegen src/abi https://example.com/erc721.json
```

--------------------------------

### Configure EVM Batch Processor

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Configure the EvmBatchProcessor for indexing Ethereum and EVM-compatible chains. Set gateway, RPC endpoint, finality confirmation, and specify fields to fetch for logs and transactions. Use this for real-time and historical data retrieval.

```typescript
import {EvmBatchProcessor} from '@subsquid/evm-processor'
import {TypeormDatabase} from '@subsquid/typeorm-store'

const processor = new EvmBatchProcessor()
    // Set Subsquid Network Gateway for fast historical data
    .setGateway('https://v2.archive.subsquid.io/network/ethereum-mainnet')
    // Set RPC endpoint for real-time data
    .setRpcEndpoint({
        url: 'https://eth-mainnet.public.blastapi.io',
        rateLimit: 10,
        requestTimeout: 30000
    })
    // Configure finality confirmation (blocks behind head considered final)
    .setFinalityConfirmation(75)
    // Select fields to fetch for each data type
    .setFields({
        block: {timestamp: true, size: true},
        log: {transactionHash: true, address: true, topics: true, data: true},
        transaction: {hash: true, from: true, to: true, value: true}
    })
    // Request Transfer events from a specific contract
    .addLog({
        address: ['0xdAC17F958D2ee523a2206206994597C13D831ec7'],
        topic0: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
        range: {from: 18000000}
    })
    // Request transactions to a contract
    .addTransaction({
        to: ['0xdAC17F958D2ee523a2206206994597C13D831ec7'],
        range: {from: 18000000}
    })

processor.run(new TypeormDatabase(), async ctx => {
    for (let block of ctx.blocks) {
        console.log(`Processing block ${block.header.number}`)
        for (let log of block.logs) {
            // Process logs
        }
        for (let tx of block.transactions) {
            // Process transactions
        }
    }
})
```

--------------------------------

### Fix Linting and Formatting with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Apply all Biome-related fixes, including linting and formatting, in one command. This ensures the code adheres to project standards.

```bash
rush biome:fix
```

--------------------------------

### Execute Command with Arguments and Flags

Source: https://github.com/subsquid/squid-sdk/blob/master/util/commands/README.md

Pass path arguments and flags directly to the script when invoking `squid-commands`. This allows for flexible command execution.

```shell
squid-commands clean --force
```

--------------------------------

### Lint Code with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Run the linter using Biome to check for code style and potential errors. This command checks the code without making changes.

```bash
# Lint
rush lint
```

--------------------------------

### Create a New Branch for Changes

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Create a new Git branch to isolate your development work. This is a standard practice before making changes.

```bash
# 1. Create a new branch to incorporate your changes
git checkout -b new_awesome_feature
```

--------------------------------

### Update Biome Autoinstaller

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Update the pinned version of the Biome autoinstaller used by the project. This ensures the latest compatible version of Biome is used.

```bash
rush update-autoinstaller --name lint
```

--------------------------------

### Generate Multicall Facade

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Use the --multicall option to generate a facade specifically for the MakerDAO multicall contract. This is useful when dealing with batched contract calls.

```bash
squid-evm-typegen --multicall src/abi 0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413
```

--------------------------------

### Generate Type Definitions from Etherscan Address

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Fetch a contract's ABI from Etherscan using its address and generate TypeScript definitions. The --etherscan-api option can specify a custom Etherscan API endpoint.

```bash
squid-evm-typegen src/abi 0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413
```

--------------------------------

### Fix Formatting Issues with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Automatically fix formatting issues in the code using Biome. This command reformats the code to comply with project standards.

```bash
rush format:fix
```

--------------------------------

### Define and Use ERC20 Events and Functions with @subsquid/evm-abi

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Defines ERC20 Transfer event and balanceOf/transfer functions using codec primitives. Shows usage within a processor for decoding logs and transactions, and for encoding/decoding function calls.

```typescript
import {event, fun, viewFun, indexed} from '@subsquid/evm-abi'
import {address, uint256, string as abiString} from '@subsquid/evm-codec'

// Define ERC20 Transfer event
export const Transfer = event(
    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    'Transfer(address indexed from, address indexed to, uint256 value)',
    {
        from: indexed(address),
        to: indexed(address),
        value: uint256
    }
)

// Define ERC20 balanceOf function (view function)
export const balanceOf = viewFun(
    '0x70a08231',
    'balanceOf(address)',
    {account: address},
    uint256  // Return type
)

// Define transfer function
export const transfer = fun(
    '0xa9059cbb',
    'transfer(address to, uint256 amount)',
    {to: address, amount: uint256},
    {success: bool}  // Return type
)

// Usage in processor
for (let log of block.logs) {
    if (Transfer.is(log)) {
        let {from, to, value} = Transfer.decode(log)
        console.log(`${from} sent ${value} to ${to}`)
    }
}

for (let tx of block.transactions) {
    if (transfer.is(tx)) {
        let {to, amount} = transfer.decode(tx)
        console.log(`Transfer call to ${to} for ${amount}`)
    }
}

// Encode function call
let calldata = balanceOf.encode({account: '0x1234...'}) 

// Decode function result
let balance = balanceOf.decodeResult('0x0000...0064')
```

--------------------------------

### Decode ink! Constructor with @subsquid/ink-abi

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-abi/README.md

Use this snippet to decode a constructor call from its hexadecimal representation using the ink! ABI. Ensure you have the ABI JSON definition available.

```typescript
import {Abi} from "@subsquid/ink-abi"

const abi = new Abi(abi_json)
const args = abi.decodeConstructor('0x9bae9d5e0000a0dec5adc9353600000000000000')
assert(args.initialSupply == 1000000000000000000000n)
```

--------------------------------

### Fix Linting Issues with Biome

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Automatically fix linting issues in the code using Biome. This command attempts to correct style and some error issues.

```bash
rush lint:fix
```

--------------------------------

### Generate EVM Types with squid-evm-typegen CLI

Source: https://context7.com/subsquid/squid-sdk/llms.txt

CLI tool to generate TypeScript types from ABI files, Etherscan contract addresses, or URLs. Supports specifying chain IDs, custom output names, multicall helpers, and cleaning the output directory.

```bash
# Generate types from a local ABI JSON file
squid-evm-typegen src/abi erc20.json

# Fetch ABI from Etherscan by contract address
squid-evm-typegen src/abi 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Specify chain ID for non-Ethereum networks
squid-evm-typegen src/abi 0x... --chain-id 137  # Polygon

# Fetch from URL
squid-evm-typegen src/abi https://example.com/abi.json

# Custom output name using fragment
squid-evm-typegen src/abi 0xdAC17F958D2ee523a2206206994597C13D831ec7#usdt

# Generate Multicall helper
squid-evm-typegen src/abi --multicall

# Clean output directory before generation
squid-evm-typegen src/abi erc20.json --clean
```

--------------------------------

### Update Vitest Autoinstaller

Source: https://github.com/subsquid/squid-sdk/blob/master/CONTRIBUTING.md

Update the pinned version of the Vitest autoinstaller. This is necessary when changes are made to the shared Vitest configuration.

```bash
rush update-autoinstaller --name vitest
```

--------------------------------

### Generate Type Definitions from JSON ABI

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Use squid-evm-typegen to generate TypeScript definitions from a local JSON ABI file. The output directory and ABI file path are required arguments.

```bash
squid-evm-typegen src/abi erc20.json
```

--------------------------------

### EVM Codec Primitives for Data Encoding/Decoding

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Provides low-level encoding and decoding primitives for EVM data types like booleans, integers, addresses, bytes, and strings. Supports complex types such as structs, fixed-size arrays, and tuples.

```typescript
import {
    bool, uint8, uint256, int256, address, bytes, bytes32, string,
    array, fixedSizeArray, struct, tuple,
    Src, Sink
} from '@subsquid/evm-codec'

// Decode raw bytes
const src = new Src(Buffer.from('0000...', 'hex'))
const value = uint256.decode(src)  // Returns bigint

// Encode values
const sink = new Sink(2)  // 2 slots
uint256.encode(sink, 1000n)
address.encode(sink, '0x1234567890123456789012345678901234567890')
const encoded = sink.result()  // Returns Buffer

// Complex types
const tokenInfo = struct({
    name: string,
    symbol: string,
    decimals: uint8,
    totalSupply: uint256
})

const decoded = tokenInfo.decode(src)
// { name: 'Token', symbol: 'TKN', decimals: 18, totalSupply: 1000000n }

// Arrays
const balances = array(uint256)
const fixedArray = fixedSizeArray(address, 3)

// Tuples (alias for struct)
const pair = tuple({token0: address, token1: address})
```

--------------------------------

### Clean Output Directory Before Generation

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Use the --clean option to automatically delete the output directory before generating new TypeScript definitions. This ensures a clean slate for the generated files.

```bash
squid-evm-typegen --clean src/abi erc20.json
```

--------------------------------

### Encode and Decode SS58 Addresses with @subsquid/ss58

Source: https://context7.com/subsquid/squid-sdk/llms.txt

Handles encoding and decoding of SS58 addresses for Substrate-based chains. Create a codec for a specific network using its name or prefix number. Use encode to convert raw bytes to an SS58 address and decode to convert an SS58 address back to raw bytes.

```typescript
import * as ss58 from '@subsquid/ss58'

// Create codec for specific network
const kusamaCodec = ss58.codec('kusama')  // Network name
const polkadotCodec = ss58.codec(0)  // Or use prefix number

// Encode raw bytes to SS58 address
const rawBytes = new Uint8Array([1, 2, 3, ...])  // 32 bytes
const address = kusamaCodec.encode(rawBytes)
// 'CxDj1Tv9PVi5XxKnPnosBUmq6NU2DYfqMkRr7q3c4oe5zHb'

// Decode SS58 address to raw bytes
const decoded = kusamaCodec.decode('CxDj1Tv9PVi5XxKnPnosBUmq6NU2DYfqMkRr7q3c4oe5zHb')
// Uint8Array(32) [1, 2, 3, ...]

// Common network prefixes
// Polkadot: 0
// Kusama: 2
// Substrate: 42
// Astar: 5
```

--------------------------------

### Overwrite Generated File Basename

Source: https://github.com/subsquid/squid-sdk/blob/master/evm/evm-typegen/README.md

Specify a custom basename for the generated TypeScript files using the '#' suffix after the ABI source. This is useful for clarity when generating definitions from contract addresses or URLs.

```bash
squid-evm-typegen src/abi 0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413#contract
```

--------------------------------

### Encode and Decode SS58 Addresses

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ss58/README.md

The `ss58.codec()` function provides methods to encode raw address bytes to an SS58 string or decode an SS58 string back into raw bytes. Ensure the network name or prefix is correct for encoding/decoding.

```typescript
ss58.codec('kusama').encode(rawAddressBytes) // => EXtQYFeY2...
ss58.codec(2).encode(rawAddressBytes) // Same as above

ss58.codec('kusama').decode('EXtQYFeY2...') // => rawAddressBytes
ss58.codec('kusama').decode(polkadotAddress) // => throws error
```

--------------------------------

### Generated Decoding Functions

Source: https://github.com/subsquid/squid-sdk/blob/master/substrate/ink-typegen/README.md

TypeScript functions generated by the typegen for decoding ink! objects. Requires an initialized Abi instance.

```typescript
// Generated code:
const _abi = new Abi(metadata)

export function decodeEvent(hex: string): Event {
  return _abi.decodeEvent(hex)
}

export function decodeMessage(hex: string): Message {
  return _abi.decodeMessage(hex)
}

export function decodeConstructor(hex: string): Constructor {
  return _abi.decodeConstructor(hex)
}
```