Onchain Orchestration Explained

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.

Why do I need onchain orchestration?

Modern DeFi operations often require multiple steps:Example: Deposit USDC into a yield vault on another chain

Approve USDC spending
Swap USDC → bridgeable asset
Bridge to destination chain
Swap back to destination USDC
Approve vault contract
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

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:

Builds optimal execution paths
Quotes total costs across all operations
Executes with guaranteed ordering
Tracks progress across chains

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.)

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" }
};

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

How does cross-chain orchestration work?

Cross-chain orchestration coordinates operations across multiple blockchains:

Source chain execution: Execute initial operations
Asset bridging: Move tokens to destination chain
Destination execution: Complete operations on target chain

Biconomy integrates with multiple bridge providers to find optimal routes:

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

What are runtime values in orchestration?

Runtime values allow later instructions to reference outputs from earlier ones. This enables truly composable workflows:

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.

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

// 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
  },
  ...
}

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.

How do I get started with orchestration?

Using AbstractJS SDK:

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:

# 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..."}'

Concepts

How-To Guides

Onchain Orchestration Explained

Onchain Orchestration Explained

Learn more about orchestration

Multi-Chain Execution

Batched Transactions

​Onchain Orchestration Explained

​Learn more about orchestration

Multi-Chain Execution

Batched Transactions

Onchain Orchestration Explained

Learn more about orchestration