> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Onchain Orchestration Explained

> Learn about onchain orchestration: coordinate complex multi-step, multi-chain blockchain operations with atomic execution and composable transaction batching

# Onchain Orchestration Explained

<Accordion title="What is onchain orchestration?">
  **Onchain orchestration** is the coordination of multiple blockchain operations across one or more chains into a unified, atomic execution flow. Instead of manually executing a series of transactions, orchestration handles:

  * **Sequencing**: Execute operations in the correct order
  * **Dependencies**: Ensure step B uses the output of step A
  * **Atomicity**: All-or-nothing execution (no partial failures)
  * **Cross-chain coordination**: Bridge assets and execute on destination chains

  Think of it as a conductor coordinating an orchestra—each instrument (transaction) plays its part at the right time to create a cohesive result.
</Accordion>

<Accordion title="Why do I need onchain orchestration?">
  Modern DeFi operations often require multiple steps:

  **Example: Deposit USDC into a yield vault on another chain**

  1. Approve USDC spending
  2. Swap USDC → bridgeable asset
  3. Bridge to destination chain
  4. Swap back to destination USDC
  5. Approve vault contract
  6. Deposit into vault

  Without orchestration, users must:

  * ❌ Execute 6+ separate transactions
  * ❌ Wait for each to confirm
  * ❌ Handle failures manually
  * ❌ Pay gas 6 times
  * ❌ Risk price slippage between steps

  With orchestration:

  * ✅ One signature, one transaction
  * ✅ Atomic execution
  * ✅ Automatic dependency handling
  * ✅ Optimal gas efficiency
</Accordion>

<Accordion title="How does Biconomy's orchestration work?">
  Biconomy's **Supertransaction** system orchestrates complex workflows:

  ```
  ┌─────────────────────────────────────────────────────────┐
  │                    Supertransaction                      │
  ├─────────────────────────────────────────────────────────┤
  │  Instruction 1: Swap ETH → USDC (Chain A)               │
  │       ↓                                                  │
  │  Instruction 2: Bridge USDC (Chain A → Chain B)         │
  │       ↓                                                  │
  │  Instruction 3: Deposit USDC to Vault (Chain B)         │
  └─────────────────────────────────────────────────────────┘
                             ↓
                      Single Signature
                             ↓
                     Atomic Execution
  ```

  The orchestration layer:

  1. **Builds** optimal execution paths
  2. **Quotes** total costs across all operations
  3. **Executes** with guaranteed ordering
  4. **Tracks** progress across chains
</Accordion>

<Accordion title="What is a Supertransaction?">
  A **Supertransaction** is Biconomy's abstraction for orchestrated blockchain operations. It combines:

  * **Instructions**: Individual operations (swaps, bridges, contract calls)
  * **Runtime values**: Dynamic values computed during execution
  * **Conditions**: Logic to control execution flow
  * **Fee configuration**: How gas is paid (sponsored, token, etc.)

  ```typescript theme={null}
  const supertransaction = {
    instructions: [
      {
        type: "intent",
        intent: "swap",
        params: { from: "ETH", to: "USDC", amount: "1.0" }
      },
      {
        type: "intent", 
        intent: "bridge",
        params: { 
          token: "USDC", 
          fromChain: 1, 
          toChain: 8453,
          amount: runtime.outputOf(0) // Uses output from first instruction
        }
      }
    ],
    feeToken: { address: "sponsored" }
  };
  ```
</Accordion>

<Accordion title="What operations can be orchestrated?">
  Biconomy supports orchestrating any EVM operation:

  | Category   | Operations                                                   |
  | ---------- | ------------------------------------------------------------ |
  | **DeFi**   | Swaps, bridges, lending, borrowing, staking, LP provisioning |
  | **NFTs**   | Minting, transfers, marketplace interactions                 |
  | **Gaming** | In-game purchases, asset transfers, crafting                 |
  | **DAOs**   | Voting, delegation, treasury management                      |
  | **Custom** | Any smart contract interaction                               |

  Operations can be:

  * **Intent-based**: "Swap 1 ETH to USDC" (solver finds best route)
  * **Explicit**: Specific contract call with exact parameters
  * **Conditional**: Execute only if certain conditions are met
</Accordion>

<Accordion title="How does cross-chain orchestration work?">
  Cross-chain orchestration coordinates operations across multiple blockchains:

  1. **Source chain execution**: Execute initial operations
  2. **Asset bridging**: Move tokens to destination chain
  3. **Destination execution**: Complete operations on target chain

  Biconomy integrates with multiple bridge providers to find optimal routes:

  ```typescript theme={null}
  const crossChainFlow = {
    instructions: [
      // Step 1: Swap on Ethereum
      {
        chainId: 1,
        type: "intent",
        intent: "swap",
        params: { from: "ETH", to: "USDC", amount: "1.0" }
      },
      // Step 2: Bridge to Base
      {
        type: "intent",
        intent: "bridge", 
        params: {
          fromChain: 1,
          toChain: 8453,
          token: "USDC"
        }
      },
      // Step 3: Deposit on Base
      {
        chainId: 8453,
        type: "call",
        to: VAULT_ADDRESS,
        data: depositCalldata
      }
    ]
  };
  ```

  The orchestrator handles:

  * Bridge selection and routing
  * Waiting for bridge confirmation
  * Gas on destination chain
  * Failure recovery
</Accordion>

<Accordion title="What are runtime values in orchestration?">
  **Runtime values** allow later instructions to reference outputs from earlier ones. This enables truly composable workflows:

  ```typescript theme={null}
  import { runtime } from "@biconomy/abstractjs";

  const instructions = [
    // Instruction 0: Swap - outputs USDC amount
    { type: "intent", intent: "swap", params: {...} },
    
    // Instruction 1: Use the EXACT output from swap
    {
      type: "call",
      to: vaultContract,
      value: 0n,
      data: encodeDeposit(runtime.outputOf(0)) // Dynamic!
    }
  ];
  ```

  Without runtime values, you'd have to estimate outputs, leading to failed transactions or leftover tokens.
</Accordion>

<Accordion title="How does orchestration handle failures?">
  Orchestration provides different failure modes:

  | Mode            | Behavior                                 | Use Case                       |
  | --------------- | ---------------------------------------- | ------------------------------ |
  | **Atomic**      | All operations succeed or all revert     | Critical multi-step operations |
  | **Partial**     | Continue after failures, collect results | Non-critical batch operations  |
  | **Conditional** | Skip steps based on conditions           | Complex branching logic        |

  ```typescript theme={null}
  // Atomic execution (default)
  const result = await execute(supertransaction);

  // With condition - only execute if balance > 0
  {
    type: "call",
    condition: {
      type: "balance",
      token: USDC_ADDRESS,
      operator: "gt",
      value: 0n
    },
    ...
  }
  ```
</Accordion>

<Accordion title="What's the difference between orchestration and aggregation?">
  | Aspect          | Aggregation                    | Orchestration                       |
  | --------------- | ------------------------------ | ----------------------------------- |
  | **Scope**       | Finding best single route      | Coordinating multiple operations    |
  | **Example**     | DEX aggregator finds best swap | Bridge + swap + deposit in one flow |
  | **Complexity**  | Single operation optimization  | Multi-step workflow management      |
  | **Cross-chain** | Usually single chain           | Native multi-chain support          |

  Orchestration *uses* aggregation for individual steps but adds coordination, dependencies, and cross-chain capabilities.
</Accordion>

<Accordion title="How do I get started with orchestration?">
  **Using AbstractJS SDK:**

  ```typescript theme={null}
  import { createMeeClient, runtime } from "@biconomy/abstractjs";

  const client = await createMeeClient({ account: smartAccount });

  // Build orchestrated transaction
  const quote = await client.getQuote({
    instructions: [
      mcUSDC.on(base.id).read.balanceOf(account.address),
      // More instructions...
    ],
    feeToken: mcUSDC.on(optimism.id)
  });

  // Execute with single signature
  const result = await client.executeQuote(quote);
  ```

  **Using Supertransaction API:**

  ```bash theme={null}
  # 1. Get quote for orchestrated operations
  curl -X POST "https://api.biconomy.io/v1/quote" \
    -H "x-api-key: $API_KEY" \
    -d '{"instructions": [...], "feeToken": {...}}'

  # 2. Execute with signature
  curl -X POST "https://api.biconomy.io/v1/execute" \
    -H "x-api-key: $API_KEY" \
    -d '{"quote": {...}, "signature": "0x..."}'
  ```
</Accordion>

***

## Learn more about orchestration

<CardGroup cols={2}>
  <Card title="Multi-Chain Execution" icon="link" href="/faq/multi-chain-execution">
    Execute across chains with one signature
  </Card>

  <Card title="Batched Transactions" icon="layer-group" href="/faq/batched-transactions-evm">
    Combine multiple operations efficiently
  </Card>
</CardGroup>