Goldsky

View saved version →

---
name: auth-setup
description: "Set up Goldsky CLI authentication and project configuration. Use this skill when the user needs to: install the goldsky CLI (what's the official install command?), run goldsky login (including when the browser opens but 'authentication failed'), run goldsky project list and see 'not logged in' or 'unauthorized', switch between Goldsky projects, check which project they're currently authenticated to, or fix 'unauthorized' errors when running goldsky turbo commands. Also use for 'walk me through setting up goldsky CLI from scratch for the first time', and when they just installed Goldsky and say 'Set it up and help me get started'. If any other Goldsky skill hits an auth error, redirect here first."
---

# Goldsky Authentication & Project Setup

Set up the Goldsky CLI, authenticate your account, and configure projects for your pipelines and subgraphs.

## Prerequisites

- [ ] macOS, Linux, or Windows with WSL (see Step 1 for binary compatibility)
- [ ] Internet connection
- [ ] A Goldsky account. Creating one happens in the browser during Step 3. Do not send the user to sign up as a separate step.

## Authentication Workflow

**Follow this workflow and verify each step. Execute commands and check results.**

### Step 1: Install and verify the CLI

Install missing tools yourself. Do not ask the user to install binaries or enter a sudo password. You run login in Step 3. The user only approves it in the browser.

On macOS and Linux (including WSL), run the bundled [installer](scripts/install.sh) from this skill's directory. Resolve that path yourself. Do not ask the user where it is.

```bash
bash scripts/install.sh
```

The default installs Goldsky, Compose, and Turbo. Pass `cli` when only the base CLI is needed. For a Compose-only or Turbo-only task, pass `compose` or `turbo`; both include the base Goldsky CLI. The script installs `@goldskycom/cli@^13.17.0` (the newest 13.x, at least 13.17.0) with `npm install --global --prefix "$HOME/.local"` (no sudo, no `@latest`), then runs `goldsky compose install` and `goldsky turbo install` for the requested extensions. If `goldsky turbo install` is not a command, it exits 1. It does not download or execute a remote shell script. Missing npm is a failure. It requires each requested command's version check to succeed. No login is needed.

**Every new shell/tool call must restore PATH**, including authentication and project commands below. An export in a previous tool call does not persist:

```bash
export PATH="$HOME/.local/bin:$HOME/.goldsky/bin:$PATH"
goldsky --version
goldsky compose --version
goldsky turbo --version
```

Check only the components requested. Do not trigger Turbo's interactive auto-installer when its binary is absent. Do not report setup complete if the installer or a required version check fails.

**Platform limits:** `goldsky turbo install` enforces the published Turbo binary limits. Do not curl a fallback and do not ask for sudo if it fails. The current Linux Turbo binary requires x64 and glibc 2.39+ (for example Ubuntu 24.04). The current Turbo Mac binary is Apple Silicon-only. Goldsky and Compose publish macOS Intel/Apple Silicon and Linux x64/ARM64 binaries, so `compose` can still be installed when Turbo cannot. Report the CLI's error. A Turbo failure is not a successful full install.

**Windows:** the complete toolset currently runs inside WSL, not native PowerShell or Git Bash: Compose has no published Windows binary. Use an existing x64 Ubuntu 24.04+ WSL distribution for all three tools. See [Windows setup](references/windows.md) for PowerShell invocation and prerequisites. Keep installation, subsequent CLI commands, project files, and `goldsky login` in the same WSL environment. Run login yourself there. Installing/enabling WSL itself may require administrator access and a reboot; do not claim that prerequisite can always be automated without intervention.

Prerequisites inside the selected environment: Bash, npm, CA certificat

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: boost
description: "Configure and troubleshoot Goldsky Boost, the free RPC caching CDN in front of a provider the user already pays for. Use for cutting RPC bills without migrating, connecting Alchemy/QuickNode/Infura upstreams, goldsky boost, edge.goldsky.com/boost, verification, cache hit rates, eth_getLogs forwarding, and x-cache / x-edge-billable / x-edge-source headers. Boost keeps the existing provider and forwards uncached requests. To replace a provider with Goldsky's managed RPC, use /edge. Pipeline, Subgraph, and Compose tasks have separate skills."
---

# Goldsky Boost

Boost is a CDN in front of the RPC endpoint the user already pays for. Every request is checked against Goldsky's indexed data first: if Boost has the answer it serves it, and the provider never sees the call (so never bills for it). If it doesn't, the request forwards to the user's endpoint unchanged and the response comes back verbatim.

**Boost is free.** CDN hits and forwarded requests both cost nothing from Goldsky. That shapes how to talk about it: there is no upsell here, and the only number that matters to the user is how much of their *existing provider bill* disappears.

## The mental model that prevents most mistakes

Three facts explain nearly every question users have:

1. **An API key *is* a Boost endpoint.** Configuration lives on the key, not in the request. The key in the URL is how Boost knows which upstream to forward to. The user's own provider URL never travels with a request.
2. **A project has exactly one Boost.** There are no named Boost endpoints to create or list. If you find yourself reaching for `goldsky boost create` or `goldsky boost list`, those commands do not exist — see [Command surface](#command-surface).
3. **Boost never guesses about the head of the chain.** Block tags always forward. This is the single most common "why didn't it cache?" question and the answer is deliberate design, not a bug.

## Endpoint format

```
https://edge.goldsky.com/boost/{chain}?key={GOLDSKY_API_KEY}
```

`{chain}` is a chain name or a chain ID, case-insensitive — `/boost/ethereum` and `/boost/1` are the same endpoint.

`?key=` is required on every request, and the two ways it can fail look different. Both verified against production:

| Request | Response | Means |
| --- | --- | --- |
| no `?key=`, `?key=` empty, or `?KEY=` (the name is **case-sensitive**) | `401`, empty body | the edge never resolved a key at all |
| `?key=<something unrecognised>` | `404` + `{"error":{"code":-32000,"message":"no Boost configuration for this key"}}` | a key was read, but it carries no Boost config |

That split is the fastest diagnostic you have: an **empty-body 401 is a malformed URL** (missing, blank, or misnamed param — check for an unset env var interpolating to nothing), while a **JSON 404 is a real key pointed at the wrong project or a Boost that was never enabled**.

The docs page says a keyless caller gets an x402 payment challenge. That is Edge's behaviour on `/standard/evm/...`, which does return `402` with a large JSON body. `/boost/...` never does. A real x402 challenge is loud, so an empty body is itself proof this isn't one — and telling a user to expect a payment challenge sends them hunting for a billing problem that cannot exist on a free product.

The key also disambiguates auth headers — see [Sending the provider's own auth](#sending-the-providers-own-auth).

### The drop-in swap

The whole value proposition is that nothing else changes. Show the user this, not a migration guide:

```typescript
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http('https://edge.goldsky.com/boost/ethereum?key=YOUR_KEY'),
})
```

Same methods, same params, same response shapes.

### Verifying it works

```bash
curl -i "https://edge.goldsky.com/boost/ethereum?key=YOUR_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: datasets
description: "Use this skill when the user needs to look up or verify Goldsky blockchain dataset names, chain prefixes, dataset types, or versions. Triggers on questions like 'what\\'s the dataset name for X?', 'what prefix does Goldsky use for chain Y?', 'what version should I use for Z?', or 'what datasets are available for Solana/Stellar/Arbitrum/etc?'. Also use for chain-specific dataset questions (e.g., polygon vs matic prefix, stellarnet balance datasets, solana token transfer dataset names), and to answer 'is there a dataset for X?' where X is a domain rather than a chain — decoded logs, token transfers and balances, mint/burn events for circulating supply, DEX or prediction-market activity (Polymarket), or the raw blocks, transactions and traces behind wallet history and reconciliation. Do NOT trigger for questions about CLI commands, pipeline setup, or general Goldsky architecture unless the core question is about finding the right dataset name or chain prefix. Wallet Feeds API queries are /feeds."
---

# Goldsky Dataset Reference

Reference tables for blockchain datasets available in Turbo pipelines.

For quick dataset questions (e.g., "what dataset for Solana transfers?"), answer directly: identify the chain prefix (see Popular Chain Prefixes below), identify the dataset type (see Common Datasets), and return a YAML snippet like:

```yaml
sources:
  my_source:
    type: dataset
    dataset_name: <chain>.<dataset>
    version: 1.0.0
    start_at: earliest
```

> **Tip:** Verify a dataset exists with `goldsky dataset get <chain>.<dataset> --outputFormat json` — returns the exact slug, version, schema, and `isTurboOnly` (`false` = usable by Turbo **and** Mirror; `true` = Turbo-only). To browse or search: `goldsky dataset list --output json` (optionally `--group <chain>`; the list is a slim index and omits `isTurboOnly` — use `dataset get` for that). `goldsky turbo validate file.yaml` validates a whole **Turbo** pipeline config — it is *not* a dataset-existence check (Turbo-specific, needs the `turbo` binary).
>
> ⚠️ **Plain `goldsky dataset list` with no flags is an interactive picker that only works in a real terminal** — in an agent/CI/piped context it produces **no output** at all. Always pass `--output json` (or `--group`). On an older CLI without those flags, fall back to the public read-only endpoint: `curl -s https://api.goldsky.com/api/public/datasets/v1`.

---

## Dataset Reference Files

> **Chain prefix and chain ID information is in the `data/` folder.**

| File                  | Contents                                           |
| --------------------- | -------------------------------------------------- |
| `chain-prefixes.json` | All chain prefixes, chain IDs, and common mistakes |

**Data location:** `data/` (relative to this skill's directory)

> **Dataset versions are not pinned in this skill.** Version numbers drift as datasets are revised, so confirm the exact version with `goldsky dataset get <name> --outputFormat json` rather than trusting a static list. The dataset-type and schema tables below are stable references; treat any version number in them as a starting point to validate, not ground truth.

---

## Quick Reference

| Action             | Command                               | Notes                        |
| ------------------ | ------------------------------------- | ---------------------------- |
| Verify a dataset     | `goldsky dataset get <name> --outputFormat json`     | **Preferred** — slug, version, schema, `isTurboOnly` |
| Search datasets      | `goldsky dataset list --output json \| grep -i name` | Non-interactive                                    |
| List all datasets    | `goldsky dataset list --output json`                 | Plain `dataset list` is TTY-only — always `--output json` |

---

## Common Datasets

| What You Need            | Dataset                    | Example                              |
| ------------------------ | -----------------

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: edge
description: "Configure and troubleshoot Goldsky Edge, Goldsky's managed EVM RPC endpoint service. Use for Edge RPC, Goldsky RPC endpoints, edge.goldsky.com, slow eth_getLogs, rate limits, hedged requests, flashblocks, HyperEVM system transactions, x402 pay-per-request RPC, pricing, the Edge dashboard, gs_edge_ keys, rpc-edge, and errors -32005/-32012/-32014/-32015/-32016. Covers resilient low-latency EVM endpoints and provider comparisons. For self-hosted eRPC configuration, consult docs.erpc.cloud/llms.txt. To keep an existing provider and reduce its bill through caching, or for x-cache / x-edge-billable / goldsky boost, use /boost. Pipeline and Subgraph questions have separate skills."
---

# Goldsky Edge (RPC Endpoints)

Goldsky Edge is a managed, high-performance RPC endpoint service for EVM blockchains, built on eRPC — an open-source fault-tolerant EVM RPC proxy. It provides globally-distributed, low-latency RPC access with intelligent routing, caching, failover, and built-in observability.

## What Edge Does

Edge sits between your application and blockchain RPC providers. It adds:

- **Performance**: Global edge infrastructure across 8+ regions, sub-100ms latency, tip-of-chain CDN caching
- **Resiliency**: Automatic failover across multiple providers for 99.9% uptime, hedged parallel requests
- **Data Integrity**: Cross-validates responses from multiple nodes, tracks block heights, enforces consensus checks
- **Cost Control**: Request deduplication, intelligent routing, configurable rate limiting
- **Indexing Optimizations**: Auto-splits large `eth_getLogs` requests, routes historical queries to archive nodes

## Quickstart

### Endpoint Format

```
https://edge.goldsky.com/standard/evm/{chainId}?secret=YOUR_SECRET
```

Replace `{chainId}` with the chain ID (e.g., `1` for Ethereum, `8453` for Base, `42161` for Arbitrum).

### Authentication

Three options:
- **Header (recommended)**: `X-ERPC-Secret-Token: YOUR_SECRET` — keeps the secret out of URLs, which are commonly logged by proxies, CDNs, and server access logs.
- **Query parameter**: `?secret=YOUR_SECRET` — convenient for quick tests, but the secret leaks into any log that records the full URL. Prefer the header for production traffic. The examples below use the query param for brevity.
- **x402 (pay-per-request)**: Clients without a secret receive an HTTP 402 response with payment requirements. An x402-compatible client signs a USDC payment and retries; Edge settles via a facilitator before forwarding the request upstream. Payment is settled on **Base** (chain `8453`) in USDC. Pricing is `$0.000005` per request (same as the standard `$5 per million` rate). See https://www.x402.org/ for the protocol spec.

### Example (curl)

```bash
curl -s "https://edge.goldsky.com/standard/evm/1?secret=YOUR_SECRET" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

### Example (viem)

```typescript
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://edge.goldsky.com/standard/evm/1?secret=YOUR_SECRET"),
});
```

### Example (ethers.js)

```typescript
import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(
  "https://edge.goldsky.com/standard/evm/1?secret=YOUR_SECRET"
);
```

## Managing Edge Endpoints in the Webapp

Edge endpoints are created and managed in the Goldsky webapp at `/dashboard/rpc-edge`.

### Creating an Endpoint

1. Navigate to the Edge RPC page (`/dashboard/rpc-edge`)
2. Click "Create endpoint"
3. Enter a name (lowercase letters, numbers, hyphens; must start with a letter; 3-50 chars)
4. Optionally select a rate limit budget
5. An API key is generated automatically (format: `gs_edge_...`)

### Endpoint Management

- **View metrics**: See request counts, error rates, and response times on the endpoint detail page
- **View logs**: S

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: feeds
description: "Query Goldsky Feeds for one wallet's balances and transfers. Use for wallet holdings, portfolio value, transfer history, deposit checks, edge.goldsky.com/data/feeds, a Feeds API key, or GOLDSKY_FEEDS_API_KEY. The same key also serves Polymarket activity, positions and balances, and block headers by number, hash or timestamp. Get the key with goldsky feeds key reveal, then call the feeds over HTTP. The CLI login token is not this key. For rows in the user's own database, use /turbo-builder. For a Turbo dataset name, use /datasets. For JSON-RPC, use /edge or /boost."
---

# Goldsky Feeds

Feeds answers one question about one wallet over HTTP: what it holds, or what it sent and received, across the supported chains in a single request. Goldsky indexes, normalizes, and prices the rows. The caller does not run a pipeline.

The same host and the same key also serve Polymarket and block-header feeds. Those are listed under "Other feeds on this key", and they do not follow the conventions below.

The CLI gets the key (`goldsky feeds key reveal`); the feeds themselves are plain HTTP. There are no `goldsky feeds` read commands. Do not mint the key with `goldsky edge create`. The endpoint name `feeds` is reserved on the Edge create path, so that command is rejected. The CLI login token is a different credential and does not authenticate these requests. Do not print the Feeds key.

## When this is the wrong tool

- The rows need to land in the user's own database or webhook. That is a Turbo pipeline (`/turbo-builder`, `/datasets`). Feeds does not stream into a sink; streaming is not offered yet (https://docs.goldsky.com/feeds/streaming).
- The question is a Turbo dataset name or chain prefix. That is `/datasets`. Those prefixes differ: Feeds says `polygon` and `arbitrum_one`, Turbo says `matic` and `arbitrum`.
- The question is JSON-RPC. That is `/edge`, or `/boost` when they want to keep their current provider.

## Key

A project has one Feeds key, and every feed answers it. Get it with the CLI. Do not send the user to the dashboard, and do not run `goldsky edge create`.

```bash
goldsky feeds key reveal
export GOLDSKY_FEEDS_API_KEY="$(cat "$HOME/.goldsky/feeds-api-key")"
```

`reveal` creates the key if the project has none, otherwise fetches the existing one, and writes it to `~/.goldsky/feeds-api-key` (mode 600). It never prints the key and never rotates it, so it is safe to run again. Do not `cat` that file into the chat, and do not write the key anywhere else.

Success prints `Created Feeds API key and saved it to ~/.goldsky/feeds-api-key` or `Saved existing Feeds API key to ~/.goldsky/feeds-api-key`. If it prints the general help instead, the CLI is older than 13.17.0 (an older CLI exits 0 there, so read the output, not the exit code); run `/auth-setup` to install the pinned version. Do not pass `--token`. A 401 means they are not logged in: use `/auth-setup` first. A 403 means the user is not an Editor on the project. A 409 means an Edge endpoint named `feeds` exists and is not the Feeds key; that endpoint has to be deleted first.

Do not rotate the key unless the user asks: rotate revokes the current key immediately.

Send the key in the `x-api-key` header. `?key=` and `Authorization: Bearer` are also accepted, but prefer the header so the key does not land in a URL log. A missing key answers 402 with an x402 payment-required body, not 401, because the feeds are also offered pay-per-request. A key that is present but wrong is 401. So on a 402, the header did not arrive; check that `GOLDSKY_FEEDS_API_KEY` is set before assuming the key is bad.

## Calls

```bash
curl -sS -H "x-api-key: $GOLDSKY_FEEDS_API_KEY" \
  "https://edge.goldsky.com/data/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
curl -sS -H "x-api-key: $GOLDSKY_FEEDS_API_KEY" \
  "https://edge.goldsky.com/data/feeds/wallets/transfers?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
```

Balances returns the la

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mirror
description: "Use this skill when the user asks about Goldsky Mirror pipelines — creating, deploying, operating, or troubleshooting Mirror. Triggers on: 'Mirror pipeline', 'goldsky pipeline apply', 'sync subgraph to database', 'mirror vs turbo', 'direct indexing', 'mirror pipeline YAML', 'mirror pipeline pause/stop/restart'. Also use this skill when the user wants to sync a Goldsky subgraph into a database or message queue — Mirror is the only pipeline product that supports subgraph sources. For new pipelines that don't need a subgraph source, the turbo-builder skill is usually a better fit. Do NOT trigger on 'goldsky turbo' commands or generic 'build a pipeline' requests without subgraph context — those belong to the turbo skills."
---

# Goldsky Mirror Pipelines

Mirror is Goldsky's original streaming pipeline product. It reads onchain data from a **source** (a subgraph entity or a direct-indexing dataset), optionally applies **transforms**, and writes the result to a **sink** (your database or message queue).

### Mirror vs Turbo — which should you use?

| | Mirror | Turbo |
|---|---|---|
| Subgraph sources | **Yes** | No |
| Speed & reliability | Good | **Faster, more reliable** |
| Sink options | See [common Mirror sinks](#sinks) below | See the [Turbo sink catalog](https://docs.goldsky.com/turbo-pipelines/sinks/overview) |
| Config complexity | Moderate | **Simpler YAML** |
| Dataset coverage | 130+ chains | 130+ chains, richer catalog |

**Use Turbo unless you need a subgraph source.** Turbo is faster, more reliable, and actively gaining feature parity with Mirror — especially sink support. If you don't have a subgraph requirement, say "help me build a Turbo pipeline" and the `/turbo-builder` skill will guide you through a faster setup.

---

## How Mirror Pipelines Work

```
Source (subgraph entity or direct-indexing dataset)
  ↓
Transforms (optional SQL or external handlers)
  ↓
Sink (PostgreSQL, ClickHouse, Kafka, S3, etc.)
```

A pipeline is defined in a YAML file (`apiVersion: 3`) and deployed with `goldsky pipeline apply`.

---

## Pipeline YAML Structure

Top-level fields:

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `name` | string | yes | Lowercase letters, numbers, hyphens only. Under 50 characters. |
| `apiVersion` | number | yes | Always `3` |
| `resource_size` | string | no | `s` (default), `m`, `l`, `xl`, `xxl` |
| `description` | string | no | Pipeline description |
| `sources` | object | yes | At least one source |
| `transforms` | object | no | Use `{}` if none needed |
| `sinks` | object | yes | At least one sink |

---

## Sources

| Source type | YAML `type` value | Description |
| ----------- | ----------------- | ----------- |
| **Subgraph entity** | `subgraph_entity` | Mirror data from Goldsky-hosted subgraphs |
| **Dataset (direct indexing)** | `dataset` | Raw onchain datasets (blocks, logs, transactions, traces, transfers) |

### Subgraph entity source

```yaml
sources:
  subgraph_account:
    type: subgraph_entity
    name: account                # Entity name in your subgraph
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter: ""                   # Optional SQL WHERE clause for fast scan
    subgraphs:
      - name: my-subgraph        # Deployed subgraph name
        version: 1.0.0
      - name: my-subgraph-arb    # Cross-chain: add more subgraphs
        version: 1.0.0
```

**Fields:** `type` (required: `subgraph_entity`), `name` (required: entity name), `subgraphs` (required: list of `{name, version}`), `start_at` (optional), `filter` (optional), `description` (optional).

### Dataset source

```yaml
sources:
  base_logs:
    type: dataset
    dataset_name: base.logs      # Use `goldsky dataset list --output json` to discover names
    version: 1.0.0               # Use `goldsky dataset get <name>` for versions
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter:

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mirror-doctor
description: "Diagnose and fix broken Goldsky Mirror pipelines. Use this skill whenever a user has a Mirror pipeline that is failing, stuck, terminated, won't start, is in a restart loop, or is blocked by an in-flight request. Also use when the user mentions a specific Mirror pipeline name alongside a problem — even if they don't say 'mirror' explicitly, if they're using `goldsky pipeline` commands (not `goldsky turbo`), this is the right skill. Runs CLI commands directly to check status, read errors, identify root cause, and apply fixes. For YAML syntax or config reference, use /mirror instead. For turbo pipeline problems, use /turbo-doctor instead."
---

# Mirror Pipeline Doctor

Diagnose and fix existing Mirror pipeline problems by running CLI commands, identifying root causes, and executing fixes.

## Boundaries

- Diagnose and fix EXISTING Mirror pipeline problems.
- Do not build new pipelines — use `/mirror` for config reference or `/turbo-builder` for new Turbo pipelines.
- Do not serve as a command reference — use `/mirror` for CLI syntax and flag lookups.
- Do not handle Turbo pipelines — use `/turbo-doctor` for `goldsky turbo` problems.
- Do not create secrets — use `/secrets` for credential management. But DO check whether secrets exist as part of diagnosis.

## Diagnostic Workflow

Follow these steps in order. Each step builds on the previous one.

### Step 1: Verify Authentication

Run `goldsky project list 2>&1` to confirm the user is logged in.

- **If logged in:** Note the project name and continue.
- **If not logged in:** Direct the user to `/auth-setup`. Do not proceed until auth works.

### Step 2: Identify the Pipeline

Run `goldsky pipeline list --include-runtime-details 2>&1` to list all Mirror pipelines with their status.

If the user already named a pipeline, confirm it exists in the list. If not, show the list and ask which pipeline they want to diagnose.

Note both the **desired status** (ACTIVE, INACTIVE, PAUSED) and the **runtime status** (STARTING, RUNNING, FAILING, TERMINATED) — Mirror pipelines have both, and the combination tells the story.

### Step 3: Triage by Status

The desired + runtime status combination determines the diagnostic path:

| Desired | Runtime | Meaning | Action |
|---------|---------|---------|--------|
| ACTIVE | RUNNING | Healthy — pipeline is processing data | Ask user what symptom they're seeing. Proceed to Step 4. |
| ACTIVE | STARTING | Pipeline is initializing | Ask how long. If >10 min, proceed to Step 4. |
| ACTIVE | FAILING | Pipeline is encountering errors but hasn't terminated yet | Proceed to Step 4 immediately — this is time-sensitive. |
| ACTIVE | TERMINATED | **Most common failure.** Pipeline wanted to run but crashed. | Proceed to Step 4. |
| PAUSED | TERMINATED | User paused the pipeline (snapshot was taken). | Ask if they want to resume: `goldsky pipeline start <name> --from-snapshot last` |
| INACTIVE | TERMINATED | User stopped the pipeline (no snapshot). | Ask if they want to start: `goldsky pipeline start <name>` |

**ACTIVE + TERMINATED is the most common case.** The pipeline's desired status is ACTIVE (it should be running) but the runtime has terminated due to an error. Focus the diagnosis here.

### Step 4: Gather Diagnostic Data

Run these commands to understand what went wrong:

```bash
# Get error details and runtime metrics
goldsky pipeline monitor <name> 2>&1

# Check for in-flight requests blocking operations
goldsky pipeline monitor <name> --update-request 2>&1

# Get the pipeline definition to check for misconfig
goldsky pipeline get <name> --definition 2>&1

# Get pipeline info including version
goldsky pipeline info <name> 2>&1

# Check available snapshots
goldsky pipeline snapshots list <name> 2>&1
```

Run these in sequence and analyze the output before proceeding. The monitor output is the most important — it shows error messages, records received/written metrics, and runtime status transitions.

### Step 5: Mat

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: secrets
description: "Use this skill when a user wants to store, manage, or work with Goldsky secrets — the named credential objects used by pipeline sinks. This includes: creating a new secret from a connection string or credentials, listing or inspecting existing secrets, updating or rotating credentials after a password change, and deleting secrets that are no longer needed. Trigger for any query where the user mentions 'goldsky secret', wants to securely store database credentials for a pipeline, or is working with sink authentication for PostgreSQL, Neon, Supabase, ClickHouse, Kafka, S3, Google Cloud Pub/Sub, Elasticsearch, DynamoDB, SQS, OpenSearch, or webhooks."
---

# Goldsky Secrets Management

Create and manage secrets for pipeline sink credentials. **Rotate existing credentials with `goldsky secret update`, preserving the secret name.** Do not delete an in-use secret to update it; see [Rotating Credentials](#rotating-credentials).

## Agent Instructions

**Handling credentials safely:** a credential passed inline via `--value '...'` is written to the user's shell history and is visible in the process list while the command runs. Whenever possible, omit `--value` on `goldsky secret create` and let the CLI prompt for the connection string interactively (nothing sensitive touches argv or history). Reserve inline `--value` for non-interactive scripting, and never echo a revealed secret (`goldsky secret reveal`) back into the conversation.

When this skill is invoked, follow this streamlined workflow:

### Step 1: Verify Login + List Existing Secrets

Run `goldsky secret list` to confirm authentication and show existing secrets.

**If authentication fails:** Invoke the `auth-setup` skill first.

### Step 2: Determine Intent Quickly

**Skip unnecessary questions.** If the user's intent is clear from context, proceed directly:

- User says "create a postgres secret" → Go straight to credential collection
- User pastes a connection string → Parse it immediately (see Connection String Parsing)
- User mentions a specific provider (Neon, Supabase, etc.) → Use provider-specific guidance

**Only use AskUserQuestion if intent is genuinely unclear.**

### Step 3: Connection String Parsing (Preferred for PostgreSQL)

**If user provides a connection string, parse it directly instead of asking questions.**

PostgreSQL connection string format:

```
postgres://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require
postgresql://USER:PASSWORD@HOST/DATABASE
```

**Parsing logic:**

1. Extract: `user`, `password`, `host`, `port` (default 5432), `databaseName`
2. Construct JSON immediately
3. Create the secret without further questions

**Example - user provides:**

```
postgresql://neondb_owner:abc123@ep-cool-name.us-east-2.aws.neon.tech/neondb?sslmode=require
```

**Create using the connection string directly:**

```bash
goldsky secret create --name SUGGESTED_NAME
# When prompted, paste the connection string:
# postgresql://neondb_owner:abc123@ep-cool-name.us-east-2.aws.neon.tech/neondb?sslmode=require
```

### Step 4: Provider-Specific Quick Paths

**No database yet? Provision a Goldsky-hosted Postgres (Scale plan or above):**

If the user doesn't already have a Postgres database, Goldsky can provision a managed Postgres (Neon) database and store its credentials as a secret in one step — no external database account required:

```bash
goldsky hosted-sink create --type postgres
```

- `--type postgres` is required; `--name` (auto-generated as `HOSTED_POSTGRES_<RANDOM>` when omitted) and `--description` are optional.
- On success it prints the created secret's **name**, **ID**, and **type**. The connection string is intentionally never printed; reference the secret by **name** as the sink `secret_name`, or run `goldsky secret reveal <name>` to view the connection string later.
- Requires the **Scale plan or above**. Without access the command fails with a Scale-plan upgrade message pointing to the team's billing page — fall back to br

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: subgraph-builder
description: "Build, author, and deploy Goldsky Subgraphs — hosted GraphQL APIs over onchain data. Use when the user wants to create, scaffold, write, or deploy a subgraph; design a schema/entities; write or fix AssemblyScript mapping handlers; configure subgraph.yaml (handlers, templates, instant/no-code from ABI); set up GraphQL endpoints, tags, or webhooks; optimize a slow subgraph (eth_calls, immutable entities); or pause/resume a subgraph. Triggers on: 'build/deploy/scaffold a subgraph', 'write a mapping', 'design a schema', 'subgraph.yaml', 'instant subgraph', 'combine/compose/merge multiple subgraphs', 'cross-chain subgraph', 'optimize indexing speed', 'too many eth_calls', 'pause/resume subgraph'. For a subgraph that is failing, stalled, erroring, or won't deploy, use /subgraph-doctor (optimizing a healthy subgraph belongs here, not the doctor). For migrating off The Graph, use /subgraph-migrate. For streaming raw chain data to a DB without GraphQL, use /turbo-builder."
---

# Subgraph Builder

Build a Goldsky Subgraph end-to-end: design the schema, write mappings, configure the manifest, then build and deploy to a hosted GraphQL endpoint. Subgraphs are best for **dApp frontends and apps that need flexible GraphQL queries** over structured onchain data. Subgraphs are **EVM-only**.

> **Default to Turbo unless the user specifically needs GraphQL.**
> Turbo is faster, more reliable, and cheaper, and needs no custom indexing code. Before building a subgraph, confirm a hosted **GraphQL API** is actually the requirement (usually: a dApp/frontend querying onchain data). If the real goal is moving onchain data into a database (PostgreSQL, ClickHouse, Kafka, S3) for analytics or a backend, build a **Turbo pipeline** instead — `/turbo-builder`. Subgraphs are the right call only for a GraphQL API or custom entity-relationship modeling. Surface this once; don't push it if they clearly want GraphQL.

## Boundaries

- Build and author NEW subgraphs (schema, mappings, manifest, deploy, endpoints, tags, webhooks).
- Do not diagnose broken/stalled subgraphs — use `/subgraph-doctor`.
- Do not run The Graph migrations — use `/subgraph-migrate`.
- For exhaustive `goldsky subgraph` flags, use `goldsky subgraph <cmd> --help` — this skill covers the workflow, not a flag dump.

## Choose an approach first

| You have… | Approach | Path |
|-----------|----------|------|
| A contract + ABI, want a GraphQL API fast, no custom logic | **Instant / no-code subgraph** | Step A |
| Custom entities, relationships, or business logic in handlers | **Code-based subgraph** | Step B |

Both deploy to the same hosted endpoint. Start with instant unless the user needs custom logic.

## Step 0: Verify Authentication

Run `goldsky project list 2>&1`. If not logged in, use `/auth-setup`.

## Step A: Instant / no-code subgraph (from ABI)

Generate and deploy directly from a contract ABI — no AssemblyScript.

```bash
# Interactive wizard (prompts for contract, network, start block, events/calls)
goldsky subgraph init

# Or one-shot from an ABI file
goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json
```

- The wizard writes a JSON config you can re-deploy and version.
- Enable contract-call indexing with `--enable-call-handlers` (only meaningful with `--from-abi`).
- For richer instant subgraphs (computed fields, `eth_call` enrichment, declared calls), see `references/schema-and-mappings.md` → "Instant subgraph enrichment".

Skip to **Step 5: Deploy**.

## Step B: Code-based subgraph

A code-based subgraph is three files: `subgraph.yaml` (manifest), `schema.graphql` (entities), and `src/` AssemblyScript mappings.

### Step 1: Scaffold

```bash
goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph
```

Useful flags: `--abi`, `--contract`, `--contract-events`, `--network`, `--start-block`. See `goldsky subgraph init --help`.

### Step 2: Design the schema

Define the entities your dApp will query in `sche

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: subgraph-doctor
description: "Diagnose and fix broken Goldsky Subgraphs. Use this skill whenever a user has a subgraph that is failing, stalled, stuck syncing, not indexing, auto-paused, returning errors, or won't deploy. Triggers on: 'subgraph stopped syncing', 'subgraph stuck at block', 'subgraph stalled', 'subgraph failed to deploy', 'indexing error', 'SubgraphSyncingFailure', 'unexpected null in handler', 'no network found', 'deployment already exists', 'subgraph not returning data', 'subgraph endpoint 404', 'reached the subgraph limit', 'rate limited'. Also use when the user names a subgraph alongside a problem. Runs CLI commands directly to check status, read logs, identify root cause, and apply fixes. For building, authoring, deploying, endpoint/tag reference, or optimizing a healthy-but-slow subgraph (e.g. too many eth_calls), use /subgraph-builder instead. For migrating from The Graph, use /subgraph-migrate instead."
---

# Subgraph Doctor

Diagnose and fix existing Goldsky Subgraph problems by running CLI commands, reading logs, identifying root causes, and executing fixes.

## Boundaries

- Diagnose and fix EXISTING subgraph problems.
- Diagnose only subgraphs that are **broken** (failing, stalled, erroring, won't deploy). A healthy but slow subgraph is an *optimization* task — use `/subgraph-builder` (e.g. reducing/declaring eth_calls).
- Do not build or scaffold new subgraphs — use `/subgraph-builder` for authoring/`init`/`deploy`.
- Do not handle The Graph migrations — use `/subgraph-migrate`.
- Do not serve as a command reference — use `/subgraph-builder` or `goldsky subgraph <cmd> --help` for CLI syntax and flag lookups.
- Do not handle Turbo or Mirror pipelines — use `/turbo-doctor` or `/mirror-doctor`.
- **Customer-facing only.** Use only `goldsky` CLI commands, the dashboard, and GraphQL queries. Never suggest `graphman`, `kubectl`, Datadog, or direct database access — those are internal Goldsky tooling. When a problem needs them, escalate to support (see Step 6).

## Mode Detection

Before running anything, check if you have the `Bash` tool:

- **Bash available (CLI mode):** Run commands directly and parse output.
- **Bash NOT available (reference mode):** Give the user one command at a time, explain what to look for, and proceed based on what they paste back.

## Diagnostic Workflow

Follow these steps in order. Each builds on the previous one.

### Step 1: Verify Authentication

Run `goldsky project list 2>&1` to confirm the user is logged in.

- **If logged in:** Note the project name and continue.
- **If not logged in:** Direct the user to `/auth-setup`. Do not proceed until auth works.

### Step 2: Identify the Subgraph

Run `goldsky subgraph list 2>&1` to list all subgraphs and their status.

If the user already named a subgraph (`name/version`), confirm it exists in the list. Otherwise show the list and ask which one to diagnose. Note its status and which **network** it indexes — a wrong network is one of the most common root causes (see Step 5).

### Step 3: Triage by Symptom

Subgraph problems fall into a few families. Pick the path that matches the symptom:

| Symptom | Likely family | Go to |
|---------|---------------|-------|
| Deploy command failed (never created) | Deploy-time error | Step 4 → "Deploy-time failures" |
| Stuck at a block / head not moving / stalled / auto-paused | Indexing stalled | Step 4 → logs + `_meta` |
| `Error` / `failed` health, indexing halted | Handler/mapping error | Step 4 → logs |
| Stuck at low % during a migration | Sync-from-scratch (slow), or handler error | Step 4 → logs + `_meta` |
| Endpoint 404 / no data / can't query | Endpoint or not-yet-synced | Step 4 → `_meta` + endpoint check |
| `reached the subgraph limit`, `database unavailable`, frozen with no log errors | Operational/quota (Goldsky-side) | Step 6 (escalate) |

### Step 4: Gather Diagnostic Data

Run these and analyze before concluding:

```bash
# Errors only — START HERE. Widen the win

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: subgraph-migrate
description: "Migrate a subgraph from The Graph to Goldsky as a drop-in replacement — no code changes required. Use this skill when the user wants to move, switch, port, or migrate a subgraph off The Graph (hosted service, Subgraph Studio, or the decentralized network) onto Goldsky, or when a subgraph endpoint they relied on (e.g. The Graph hosted service) was sunset. Triggers on: 'migrate from The Graph', 'move my subgraph to Goldsky', 'switch off The Graph', 'redeploy a TheGraph subgraph', 'my subgraph endpoint is gone', 'from-url', 'from-ipfs-hash', 'drop-in replacement for The Graph'. For diagnosing a subgraph that fails after migrating, use /subgraph-doctor. For building/authoring or general deploy/tag/endpoint reference, use /subgraph-builder."
---

# Migrate a Subgraph from The Graph

Migrating an existing subgraph from The Graph to Goldsky is a **drop-in replacement** — you don't change your subgraph code. You point Goldsky at your published subgraph (by URL or IPFS hash) or redeploy from source, then swap the endpoint your app queries.

> **Worth a quick check first: do they still need a subgraph?**
> Migration is a natural moment to reconsider. If the dApp needs a hosted **GraphQL API**, migrating the subgraph is the right move — continue below. But if the real goal is getting this data into a database for analytics or a backend, a **Turbo pipeline** is faster, more reliable, and cheaper (`/turbo-builder`) — they may not need a subgraph at all. Surface this once; if they clearly want GraphQL, proceed with the migration.

## Boundaries

- This skill is for migrating **from The Graph** (hosted service, Subgraph Studio, or decentralized network).
- For diagnosing a subgraph that fails to deploy or sync after migrating, use `/subgraph-doctor`.
- For deploy/tag/endpoint/webhook reference, use `/subgraph-builder`.
- For migrating from Alchemy, follow the dedicated Alchemy migration docs (not covered here).

## Two hard rules

> **1. Never invent the source URL or IPFS hash.** Always have the user provide their actual deployment URL or IPFS hash. Do not construct or guess `api.thegraph.com/...` or gateway URLs — fabricated source URLs are a top failure mode and waste deploy attempts. If you don't have a verified source, ask for it (see Step 2).

> **2. Never quote pricing.** Do not tell the user migration is "free" or "cheap" or estimate a price. Subgraph pricing depends on usage and plan, and a wrong guess erodes trust (one customer was told "cheap" then quoted $10k+). For any cost question, route them to a Goldsky quote: support@goldsky.com or their account/sales contact.

## Step 1: Choose a migration path

| You have… | Use | Notes |
|-----------|-----|-------|
| A public GraphQL endpoint for the deployed subgraph | `--from-url <url>` | Simplest. Works for publicly deployed subgraphs. |
| The subgraph's IPFS hash (deployment ID) | `--from-ipfs-hash <hash>` | Use when you have the hash but not a queryable URL. |
| The original source code locally | `--path .` (build first) | Use if the published version is unavailable or you want to change code. |

Recommend `--from-url` when the user has a working endpoint; otherwise `--from-ipfs-hash`.

## Step 2: Get the real source identifier

Before deploying, get the user's actual source — do not guess it.

- **From-URL:** Ask the user to paste the GraphQL endpoint they currently query on The Graph.
- **From-IPFS-hash:** The IPFS hash is the deployment ID (`Qm...`). The user can find it on The Graph's explorer/Studio, or by querying their existing endpoint:
  ```graphql
  { _meta { deployment } }
  ```
  `deployment` is the IPFS hash.

If the user can't produce either, fall back to deploying from source (`--path`) and point them to `/subgraph-builder` for `init`/build.

## Step 3: Install the CLI and log in

CLI setup is the most common migration sticking point — confirm it before deploying.

```bash
# Follow /auth-setup and run its installer with cli; Wi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: turbo-builder
description: "Build and deploy new Goldsky Turbo pipelines: requirements, dataset selection, YAML, validation, and deployment. Use for 'build a pipeline', 'index X on Y chain', or moving chain/contract data into Postgres, MySQL, ClickHouse, Kafka, Pub/Sub, S3, SQS, or webhooks. Also use for data goals such as Polymarket fills/positions/PnL, prediction markets, stablecoin or circulating supply, proof of reserves, sanctions/AML transfer monitoring, deposit detection, CCTP burns/mints, cross-chain settlement, payment reconciliation, wallet history streamed into the user's own database, token holder registries, tokenized equities/RWA, and wash-trading detection. A REST lookup of one wallet's balances or transfers is /feeds, not a pipeline, and so is a read of Polymarket activity, positions or balances. Debug existing pipelines with /turbo-doctor; look up syntax with /turbo-pipelines."
---

# Pipeline Builder

## Boundaries

- Build NEW pipelines. Do not diagnose broken pipelines — that belongs to `/turbo-doctor`.
- Do not serve as a YAML reference. If the user only needs to look up a field or syntax, use the `/turbo-pipelines` skill instead.
- For dataset lookups, use `/datasets`.
- A REST lookup of one wallet's balances or transfers is `/feeds`. Build a pipeline only when the rows need to land in the user's own database or webhook.

Walk the user through building a complete pipeline from scratch, step by step. Generate a valid YAML configuration, validate it, and deploy it.

## Builder Workflow

### Step 1: Verify Authentication

Run `goldsky project list 2>&1` to check login status.

- **If logged in:** Note the current project and continue.
- **If not logged in:** Use the `/auth-setup` skill for guidance.

### Step 2: Understand the Goal

Ask the user what they want to index. Good questions:

- What blockchain/chain? (Ethereum, Base, Polygon, Solana, etc.)
- What data? (transfers, swaps, events from a specific contract, all transactions, etc.)
- Where should the data go? (PostgreSQL, ClickHouse, Kafka, S3, etc.)
- Do they need transforms? (filtering, aggregation, enrichment)
- One-time backfill or continuous streaming?

If the user already described their goal, extract answers from their description.

### Step 3: Choose the Dataset

Use the `/datasets` skill to find the right dataset.

Key points:
- Common datasets: `<chain>.raw_logs`, `<chain>.raw_transactions`, `<chain>.erc20_transfers`, `<chain>.raw_traces`
- For decoded contract events on EVM chains: source from `<chain>.raw_logs` with a filter on `address` ONLY, then add a SQL transform that calls `_gs_log_decode(_gs_fetch_abi(<explorer-url>, <source>), topics, data) AS decoded`, then filter downstream by `WHERE decoded.event_signature = '<EventName>(<types>)'`. Never put topic0 hashes in the source filter — see `/turbo-transforms` for the full pattern. There is no consumable `<chain>.decoded_logs` dataset; decoding always happens in a transform.
- For pre-decoded common token events: `<chain>.erc20_transfers`, `<chain>.erc721_transfers`, `<chain>.erc1155_transfers` are available and don't need decoding transforms.
- For Solana: use `solana.transactions`, `solana.token_transfers`, etc.

Present the dataset choice to the user for confirmation.

### Step 4: Configure the Source

Build the source section of the YAML:

```yaml
sources:
  my_source:
    type: dataset
    dataset_name: <chain>.<dataset>
    version: 1.0.0
    start_at: latest  # REQUIRED — see below. `latest` or `earliest` (Solana uses `start_block` instead)
```

**A start position is required, not optional.** Never emit a dataset source without an explicit `start_at` — that is the field on EVM, NEAR, Bitcoin, and Stellar. Omitting it does not mean "start now": the backend starts from the earliest available data, so the pipeline silently backfills the entire chain history. That is how a pipeline ends up running for days, writing millions of rows, and filling its sink before it ever reache

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: turbo-doctor
description: "Diagnose and fix broken Goldsky Turbo pipelines interactively. Triggers on: pipeline in error state, stuck starting, connection refused, not getting data, duplicate rows, missing fields, slow backfill, or any named pipeline misbehaving. Runs logs/status commands, identifies root cause, and offers fixes. For CLI syntax or error pattern lookup without an active problem, use /turbo-operations instead."
---

# Pipeline Doctor

## Boundaries

- Diagnose and fix EXISTING pipeline problems interactively.
- Do not build new pipelines — that belongs to `/turbo-builder`.
- Do not serve as a command reference. If the user only needs CLI syntax or error pattern lookup, use the `/turbo-operations` skill instead.

Systematically identify and resolve pipeline issues by following a structured diagnostic workflow.

## Mode Detection

Before running any commands, check if you have the `Bash` tool available:

- **If Bash is available** (CLI mode): Execute commands directly and parse output.
- **If Bash is NOT available** (reference mode): Output commands for the user to run. Ask them to paste the output back so you can analyze it and provide recommendations.

## Diagnostic Workflow

Follow these steps in order. Do not skip steps — each builds on the previous one.

### Step 1: Verify Authentication

Run `goldsky project list 2>&1` to check login status.

- **If logged in:** Note the current project and continue.
- **If not logged in:** Tell the user they need to authenticate. Use the `/auth-setup` skill for guidance. Do not proceed until auth is confirmed.

### Step 2: Identify the Pipeline

Run `goldsky turbo list` to show all pipelines.

Ask the user which pipeline they want to diagnose. If they already named one, confirm it exists in the list.

Note the pipeline's current status (running, paused, error, completed, starting).

### Step 3: Analyze Pipeline Status

Based on the status:

- **running** — Pipeline is active. Check if the issue is data quality, latency, or unexpected behavior. Proceed to Step 4.
- **error** — Pipeline has failed. This is the most common case. Proceed to Step 4 for log analysis.
- **paused** — Pipeline was manually paused. Ask if they want to resume it.
- **starting** — Pipeline is initializing. Ask how long it's been starting. If >10 minutes, check logs.
- **completed** — Job-mode pipeline finished. Ask what the expected vs actual behavior was.

### Step 4: Examine Logs

Run `goldsky turbo logs <pipeline-name> --tail 100 2>&1` to get recent logs.

Analyze the output for known error patterns. Reference the error patterns in the `/turbo-operations` skill, including:

- **Connection errors** — sink unreachable, auth failed, timeout
- **Schema errors** — column mismatch, type mismatch, missing columns
- **Resource errors** — OOM, disk full, rate limiting
- **Data errors** — deserialization failures, invalid block ranges
- **Configuration errors** — invalid YAML, unknown dataset, bad transform

### Step 5: Check Secrets (if applicable)

If logs show connection or authentication errors:

Run `goldsky secret list` to verify all required secrets exist.

Cross-reference with the pipeline YAML if available. Use the `/secrets` skill for guidance on creating or updating secrets.

### Step 6: Provide Diagnosis

Present your findings in this format:

```
## Diagnosis

**Pipeline:** [name]
**Status:** [status]
**Issue:** [one-line summary]

**Root cause:**
[Detailed explanation of what's wrong]

**Evidence:**
- [Log line or observation 1]
- [Log line or observation 2]

**Recommended fix:**
1. [Step 1]
2. [Step 2]

**Prevention:**
[How to avoid this in the future]
```

### Step 7: Offer to Fix

If the fix involves CLI commands (restart, update secrets, redeploy), offer to execute them. Always confirm with the user before making changes.

Common fixes:
- **Restart:** `goldsky turbo restart <name>` (or `--clear-state` for a fresh start)
- **Update secret:** Use `goldsky secret update <name> --value

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: turbo-operations
description: "Turbo pipeline operations reference — lifecycle commands (pause, resume, restart, delete), pipeline states, checkpoint behavior, streaming vs job-mode differences, CLI syntax for `inspect`/`logs`, TUI shortcuts, and error pattern lookup. Triggers on: 'how do I pause/restart/delete', 'will deleting lose my data', 'what does this error mean', 'inspect TUI shortcuts'. For interactive diagnosis of a broken pipeline, use /turbo-doctor."
---

# Turbo Pipeline Operations

Lifecycle commands, monitoring, and error reference for running Turbo pipelines. This is a lookup reference — for interactive troubleshooting of a broken pipeline, use `/turbo-doctor`. For building new pipelines, use `/turbo-builder`.

## Pipeline States

| State     | Description                                  |
| --------- | -------------------------------------------- |
| running   | Pipeline is actively processing data         |
| starting  | Pipeline is initializing                     |
| paused    | Pipeline is paused (replicas set to 0)       |
| stopped   | Pipeline is not running (manually stopped)   |
| error     | Pipeline encountered an error                |
| completed | Job-mode pipeline finished processing range  |

## Streaming vs Job Mode Lifecycle

| Operation     | Streaming Pipeline            | Job-Mode Pipeline (`job: true`)             |
| ------------- | ----------------------------- | ------------------------------------------- |
| **List**      | Shows as `running`/`paused`   | Shows as `running`/`completed`              |
| **Pause**     | Supported                     | Not supported                               |
| **Resume**    | Supported                     | Not supported                               |
| **Restart**   | Supported                     | Not supported — use delete + apply          |
| **Delete**    | Supported                     | Supported (auto-cleanup ~1hr after done)    |
| **Apply**     | Updates in place              | Must delete first, then re-apply            |

### Job-Mode Pipeline Lifecycle

Job-mode pipelines (`job: true`) are one-time batch processes:

1. **Start** — process data from `start_at` to `end_block`
2. **Run** — process the bounded data range
3. **Complete** — automatically stop when range is processed
4. **Auto-cleanup** — ~1 hour after completion, automatically removed

Cannot pause, resume, or restart. Must delete before redeploying.

## Lifecycle Commands

### List Pipelines

```bash
goldsky turbo list
```

### Pause a Pipeline

Temporarily stop processing without deleting. Preserves all state for later resumption.

```bash
goldsky turbo pause <pipeline-name>
```

### Resume a Pipeline

Restore a paused pipeline. Can only resume a **paused** pipeline.

```bash
goldsky turbo resume <pipeline-name>
```

### Restart a Pipeline

Trigger a pod restart for a running or paused pipeline.

```bash
goldsky turbo restart <pipeline-name>
# To clear all checkpoints and reprocess from the beginning:
goldsky turbo restart <pipeline-name> --clear-state
```

### Delete a Pipeline

Permanently remove a pipeline. All checkpoints are lost. Data already written to sinks is preserved.

```bash
goldsky turbo delete <pipeline-name>
```

### Delete and Recreate (Fresh Start)

```bash
goldsky turbo delete my-pipeline
goldsky turbo apply my-pipeline.yaml
```

## Checkpoint Behavior

- Deleting a pipeline removes its checkpoints permanently
- Recreating with the same name starts fresh (no checkpoint recovery)
- To preserve checkpoints, use `apply` to update instead of delete/recreate
- Checkpoint state is tied to source names — renaming a source resets its checkpoint
- Checkpoint state is tied to pipeline names — renaming a pipeline resets all checkpoints

## Monitoring Commands

| Action                   | Command                                              |
| ------------------------ | ---------------------------------------------------- |
| List pipelines           

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: turbo-pipelines
description: "Turbo pipeline YAML reference and architecture guide. Covers: YAML field syntax (start_at, from, version, primary_key), source/transform/sink configuration, validation errors, resource sizing (xs–xxl), architecture decisions (dataset vs kafka, streaming vs job, fan-out vs fan-in, sink selection, pipeline splitting). Triggers on: 'what does field X do', 'what fields does a postgres sink need', 'what resource size', 'should I use kafka or dataset', 'how to structure my pipeline'. For writing transforms, use /turbo-transforms. For end-to-end building, use /turbo-builder."
---

# Turbo Pipeline Configuration & Architecture

YAML configuration reference and architecture guide for Turbo pipelines. For interactive pipeline building, use `/turbo-builder`. For troubleshooting, use `/turbo-doctor`. For transform implementation, use `/turbo-transforms`.

**Decoded contract events are transform output, not a consumable `<chain>.decoded_logs` dataset.** Source EVM contract logs from `<chain>.raw_logs`, then decode them in a transform (see `/turbo-transforms`). Pre-decoded token datasets such as `<chain>.erc20_transfers`, `<chain>.erc721_transfers`, and `<chain>.erc1155_transfers` are separate, available datasets; use `/datasets` to verify chain coverage.

> **CRITICAL:** Always validate YAML with `goldsky turbo validate <file.yaml>` before showing complete pipeline YAML to the user or deploying.

---

## Quick Start

```yaml
name: my-first-pipeline
resource_size: s
sources:
  transfers:
    type: dataset
    dataset_name: base.erc20_transfers
    version: 1.2.0
    start_at: latest
transforms: {}
sinks:
  output:
    type: blackhole
    from: transfers
```

```bash
goldsky turbo validate pipeline.yaml   # Validate first
goldsky turbo apply pipeline.yaml -i   # Deploy + inspect
```

## Prerequisites

- **Goldsky CLI** — if `goldsky` is not on PATH, follow `/auth-setup`
- **Turbo extension** — follow `/auth-setup` and run its bundled installer with `turbo`. Do not trigger the interactive auto-installer. Verify `goldsky turbo --version` succeeds; the published Linux binary requires x64 and glibc 2.39+, and the Mac binary requires Apple Silicon. Windows uses the WSL entry point. An unsupported platform is not a successful installation.
- **Shell PATH** — restore `export PATH="$HOME/.local/bin:$HOME/.goldsky/bin:$PATH"` in every new shell/tool call; exports do not persist across calls.
- **Logged in** — follow `/auth-setup` and run `goldsky login` yourself when `goldsky project list` is not authenticated
- Secrets created for sinks if using PostgreSQL, ClickHouse, Kafka, etc. (see `/secrets`)

---

## Architecture Decisions

### Source Type Selection

| Scenario                          | Source Type | Why                                          |
| --------------------------------- | ----------- | -------------------------------------------- |
| Decode contract events from logs  | `dataset`   | Need `raw_logs` + `_gs_log_decode()`         |
| Track token transfers             | `dataset`   | `erc20_transfers` has structured data        |
| Historical backfill + live        | `dataset`   | `start_at: earliest` processes history       |
| Live token balances               | `kafka`     | `latest_balances_v2` is a streaming topic    |
| Real-time state snapshots         | `kafka`     | Kafka delivers latest state continuously     |
| Only need new data going forward  | Either      | Dataset with `start_at: latest` or Kafka     |

> **Note:** Kafka sources are used in production but are not documented in official Goldsky docs. Contact Goldsky support for topic names.

### Data Flow Patterns

| Pattern              | When to Use                                          | Template                           |
| -------------------- | ---------------------------------------------------- | ---------------------------------- |
| **Linear**           | Single source, single destination, simple processing | `templa

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 15 — file references are metadata, not package contents.

View saved version →

---
name: turbo-transforms
description: "Write SQL, TypeScript, and dynamic table transforms for Turbo pipelines. Covers: decoding EVM logs with _gs_log_decode, filtering/casting blockchain data, UNION ALL for combining events, TypeScript/WASM transforms (invoke function), dynamic lookup tables (dynamic_table_check), transform chaining, and Solana decoding. Triggers on: 'decode Transfer events', 'write a SQL transform', 'filter by contract', 'TypeScript transform', 'dynamic table', 'UNION ALL'. For pipeline YAML structure, use /turbo-pipelines. For end-to-end building, use /turbo-builder."
---

# Turbo Transforms

Write, understand, and debug SQL, TypeScript, and dynamic table transforms for Turbo pipeline configurations.

Identify what the user needs (decode, filter, reshape, combine, custom logic, or lookup joins), then use the relevant section below. If generating a complete pipeline YAML (not just a transform snippet), always validate with `goldsky turbo validate` before presenting it to the user.

**Reference files for specialized topics:**
- `references/evm-patterns.md` — Advanced EVM patterns (decode-once-filter-many, UNION ALL, schema normalization)
- `references/typescript-transforms.md` — TypeScript/WASM script transforms and handler transforms
- `references/dynamic-tables.md` — Dynamic table transforms (allowlists, lookup joins)
- `references/solana-patterns.md` — Solana instruction/log decoding and function examples

---

## Transform Basics

### YAML Structure

```yaml
transforms:
  my_transform:
    type: sql
    primary_key: id
    sql: |
      SELECT id, block_number, address
      FROM my_source
      WHERE address = '0xabc...'
```

### Required Fields

| Field         | Required | Description                                                  |
| ------------- | -------- | ------------------------------------------------------------ |
| `type`        | Yes      | `sql`, `script`, `handler`, `dynamic_table`, or `throttle`   |
| `primary_key` | Yes\*    | Column used for uniqueness and ordering (\*not for `throttle`) |
| `sql`         | Yes      | SQL query (for `sql` type transforms)                        |

### Referencing Data

- Reference **sources** by their YAML key name: `FROM my_source`
- Reference **other transforms** by their YAML key name: `FROM my_transform`
- No need for a `from` field in SQL transforms — the `FROM` clause in SQL handles it

### SQL Streaming Limitations

Turbo SQL is powered by Apache DataFusion in streaming mode. The following are **NOT supported**:

- **Joins** — use `dynamic_table` transforms for lookup-style joins instead
- **Aggregations** (GROUP BY, COUNT, SUM, AVG) — use `postgres_aggregate` sink instead
- **Window functions** (OVER, PARTITION BY, ROW_NUMBER)
- **Subqueries** — use transform chaining instead
- **CTEs** (WITH...AS) **are** supported

### The `_gs_op` Column

Every record includes a `_gs_op` column that tracks the operation type: `'i'` (insert), `'u'` (update), `'d'` (delete). Preserve this column through transforms for correct upsert semantics in database sinks.

---

## Key SQL Functions

Quick reference for the most-used functions. For the complete function reference, see [SQL transforms](https://docs.goldsky.com/turbo-pipelines/transforms/sql) in the docs.

### `evm_log_decode()` — Decode Raw EVM Logs

```sql
evm_log_decode(abi_json, topics, data) -> STRUCT<name, event_params>
-- Aliases: _gs_log_decode, evm_decode_log
```

Returns `decoded.event_signature` (event name) and `decoded.event_params[N]` (1-indexed parameters as strings).

**Example:**
```sql
SELECT
  _gs_log_decode('[{"anonymous":false,"inputs":[{"indexed":true,"name":"from","type":"address"},{"indexed":true,"name":"to","type":"address"},{"indexed":false,"name":"value","type":"uint256"}],"name":"Transfer","type":"event"}]',
    topics, data) AS decoded,
  id, block_number, transaction_hash, address, block_timestamp
FROM my_raw_logs
```

**Tips:** Backtick-escape reserved words (`` `data` ``, `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.