---
name: orquestra-solana
description: |
  End-to-end guide for executing Solana transactions via the Orquestra agent pipeline.
  Use when performing any Solana operation: staking, swapping, minting, transferring,
  or any Anchor program interaction using the Orquestra agents.
  Triggers: "stake sol", "swap token", "solana transaction", "use orquestra to",
  "send transaction", "interact with program", "call instruction", "build and sign",
  "orquestra pipeline", "full pipeline", "execute on solana", "solana agent",
  "marinade deposit", "jupiter swap", "mint token", "transfer spl".
---

<!--
  Mirror of https://github.com/berkayoztunc/orquestra/blob/18ac4aa4829d823deb690eeb600331d96871fe73/.claude/skills/orquestra-solana/SKILL.md hosted by skills.solana.com.
  Relative links were rewritten to GitHub URLs pinned to the mirrored commit —
  companion files are not hosted here; the upstream repo is the source of truth.
-->


# Orquestra Solana Pipeline

The Orquestra agent pipeline executes Solana tasks end-to-end in 4 stages.
Each stage is a specialized sub-agent. The `orquestra` orchestrator manages them.

## Pipeline Overview

```
User intent
    │
    ▼
[1] orquestra-researcher   — find program, list instructions + PDAs
    │
    ▼
[2] orquestra-pda-explorer — derive PDAs, resolve all required accounts
    │
    ▼
[3] orquestra-tx-builder   — build unsigned base64 wire transaction
    │
    ▼
[3.5] orquestra-simulator  — preflight: compute units, Anchor error decode
    │
    ▼ (user confirms)
[4] orquestra-signer       — sign + send, explicit YES required
```

## How to Start

Say the task in plain English to the `orquestra` orchestrator:

> "Stake 2 SOL with Marinade for wallet `9xTy...pQr2`"
> "Swap 1 SOL to USDC on Jupiter"
> "Derive the stake account PDA for Marinade"
> "What instructions does the Kamino lending program have?"

The orchestrator decides which stages to run. Research-only tasks stop at Stage 1.

---

## Stage 1 — Research (orquestra-researcher)

**What it does**: searches the Orquestra registry, reads docs, lists instructions and PDA schemas.

**MCP tools used**: `search_programs`, `read_llms_txt`, `list_instructions`, `list_pda_accounts`, `get_ai_analysis`

**What you get back**:
- Program name + projectId
- All instructions (name, args, accounts)
- All PDA account types + seed schemas

**You only need to provide**: program name or keyword (e.g. "Marinade", "Jupiter", "Kamino")

---

## Stage 2 — Account Resolution (orquestra-pda-explorer)

**What it does**: derives every PDA address required by the instruction.

**MCP tools used**: `list_pda_accounts`, `derive_pda`, `fetch_pda_data` (via Orquestra MCP)

**What you need to provide**:
- Your wallet public key (fee payer / authority / signer)
- Any token mint addresses if the instruction requires them
- Any other user-provided seeds (amounts are NOT seeds)

**What the agent resolves automatically**:
- All PDAs derivable from your wallet + known program constants
- Nested PDAs (fetches on-chain data to extract further addresses)

**What it asks you for**: ONLY seeds it cannot derive — it names the exact field.

---

## Stage 3 — Transaction Build (orquestra-tx-builder)

**What it does**: calls `build_instruction` with all resolved accounts and your provided args.

**MCP tools used**: `build_instruction`

**What you must have ready**:
- All account addresses (from Stage 2)
- All argument values (amounts in correct units — see below)
- Fee payer wallet pubkey

**Returns**: unsigned base64 wire transaction + risk level + estimated fee

### Amount Units

| Token | Unit | Example: 1 SOL |
|-------|------|----------------|
| SOL | lamports (u64) | `1000000000` |
| USDC | micro-USDC (u64, 6 decimals) | `1000000` |
| SPL token | raw units (check token decimals) | varies |

---

## Stage 3.5 — Simulation (orquestra-simulator)

**What it does**: preflights the transaction. No wallet interaction. Decodes Anchor errors.

**MCP tools used**: `simulate_instruction`

**Simulation passes** → shows compute units consumed → proceeds to signer
**Simulation fails** → shows decoded Anchor error (`name`, `code`, `msg`) → STOPS

If simulation fails, fix the error before asking to sign. Common failures:
- `InsufficientFunds` — wallet balance too low
- `InvalidAccountData` — wrong PDA seed / account type mismatch
- `AccountNotInitialized` — an account must be created first
- Custom Anchor error — check `decodedError.msg` for constraint name

---

## Stage 4 — Sign & Send (orquestra-signer)

**What it does**: shows approval summary, waits for explicit YES, then signs and submits.

**MCP tools used**: `get_signer_address`, `sign_and_send_transaction` (signer-mcp)

**Approval summary shown before every signature**:
```
Network:        mainnet-beta
Signer Wallet:  <your pubkey>
Program:        <program name>
Instruction:    <instruction>
Estimated Fee:  <lamports>
Risk Level:     LOW / MEDIUM / HIGH
```

Type **YES** to sign. Any other response cancels.

**Returns on success**:
```
Tx Signature: <base58>
Explorer: https://explorer.solana.com/tx/<sig>?cluster=mainnet-beta
```

---

## Solana Constants (used as accounts, not user input)

| Program | Address |
|---------|---------|
| System Program | `11111111111111111111111111111111` |
| SPL Token | `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` |
| Token-2022 | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` |
| ATA Program | `ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL` |
| Sysvar Rent | `SysvarRent111111111111111111111111111111111` |

---

## Research-Only Mode

If you only want program info (no transaction), say so explicitly:

> "What instructions does Marinade have?" → Stage 1 only, no transaction built
> "Show me the PDA accounts for Kamino" → Stage 1 + Stage 2, stops before build
> "What is the AI analysis for Jupiter?" → `get_ai_analysis` only

---

## Hard Rules

- NEVER invent account addresses or PDA values — agent derives them from chain data
- NEVER skip simulation — always run before signing
- NEVER assume token amounts — ask for clarification if units are ambiguous
- Signing requires **explicit YES** — ambiguous confirmation is NOT approval