Context Functions - Compose

Context functions allow task sandboxes to access the outside world. Context functions support individual retry configuration and are automatically logged for auditing and debugging. All communication outside of the task sandbox happens via Context Functions, making Compose apps run deterministic, given the same world context.

Retry Configuration

All Context functions accept an optional retry configuration:

type ContextFunctionRetryConfig = {
  max_attempts: number; // 3 for read-only calls, 1 for mutations
  initial_interval_ms: number; // Default: 500
  backoff_factor: number; // Default: 2
};

How Context Function Retries Work:

Each context function call can have its own retry configuration
If a context function fails, it retries according to its configuration
If all context function retries are exhausted, the context function will throw
If you don’t catch a failed context function call, a task-level retry may trigger, restarting the task and any context-function retries

Durable execution and context caching

Compose provides durable execution guarantees. All context function calls are deterministically cached — if a task is interrupted (e.g. by a restart or deployment) and resumed, context functions that already completed will return their cached results instead of re-executing. This means:

Transactions that already succeeded will not be re-sent
Fetch calls that already returned will not be re-made
Collection operations that already completed will not be repeated

This caching is scoped to each individual task run. Cached results are automatically cleaned up when the run completes (success or failure). Non-deterministic values, such as timestamps or random IDs, must be produced through ctx.sideEffect() so a replay returns the same value instead of recomputing it.

By default, read-only context calls make up to 3 attempts (max_attempts: 3, initial_interval_ms: 500, backoff_factor: 2). This covers readContract, simulate, getBalance, and ctx.fetch with GET, HEAD, or OPTIONS. Mutations such as callTask, writeContract, sendTransaction, and ctx.fetch with POST, PUT, PATCH, or DELETE default to a single attempt (max_attempts: 1). Pass a retryConfig to override either default.

Overview of key context properties and functions

Here’s a brief overview of what context enables. Use the left nav or links below to find full reference docs.

State Management - Collections
Blockchain Interactions - evm
HTTP requests - fetch
Task to task execution - callTask
Non-deterministic values - sideEffect
Reading env variables - env
Reorg handling - Reorgs
Turbo pipeline management - turbo
Run-aware logging - logger

Full TaskContext interface

export type ContextFunctionRetryConfig = {
  max_attempts: number;
  initial_interval_ms: number;
  backoff_factor: number;
};

export type Chain = {
  id: number;
  name: string;
  testnet: boolean;
  nativeCurrency: {
    name: string;
    symbol: string;
    decimals: number;
  };
  rpcUrls: {
    public: { http: string[] };
    default: { http: string[] };
  };
  blockExplorers: {
    default: { name: string; url: string };
  };
  contracts?: Record<string, { address: string }>;
};

export type ScalarIndexType = "text" | "numeric" | "boolean" | "timestamptz";

export interface CollectionIndexSpec {
  path: string;
  type: ScalarIndexType;
  unique?: boolean;
}

export interface FindOptions {
  limit?: number;
  offset?: number;
}

// Filter helpers for comparison operators
export type FilterHelper =
  | "$gt"
  | "$gte"
  | "$lt"
  | "$lte"
  | "$in"
  | "$ne"
  | "$nin"
  | "$exists";
export type HelperValue = Partial<
  Record<FilterHelper, string | number | boolean | string[] | number[]>
>;
export type FilterValue = string | number | boolean | HelperValue;
export type Filter = Record<string, FilterValue>;

export type WithId<T> = T & { id: string };

export interface Collection<TDoc = unknown> {
  readonly name: string;
  insertOne(doc: TDoc, opts?: { id?: string }): Promise<{ id: string }>;
  findOne(filter: Filter): Promise<WithId<TDoc> | null>;
  findMany(filter: Filter, options?: FindOptions): Promise<Array<WithId<TDoc>>>;
  getById(id: string): Promise<WithId<TDoc> | null>;
  /**
   * @param opts.upsert - Defaults to true. Set to false to throw if document doesn't exist.
   */
  setById(
    id: string,
    doc: TDoc,
    opts?: { upsert?: boolean },
  ): Promise<{ id: string; upserted?: boolean; matched?: number }>;
  deleteById(id: string): Promise<{ deletedCount: number }>;
  drop(): Promise<void>;
}

export type Address = `0x${string}`;

export interface WalletConfig {
  name?: string; // defaults to "default"
  privateKey?: string;
  sponsorGas?: boolean; // defaults to true for Privy wallets, false for private key wallets
}

export type ReplayOnReorg = {
  type: "replay";
};

export type LogOnReorg = {
  type: "log";
  logLevel?: "error" | "info" | "warn"; // defaults to "error"
};

export type CustomReorgAction = {
  type: "task";
  // your task will be sent with a payload the full transaction minus gas and nonce
  task: string;
};

export type OnReorgOptions = ReplayOnReorg | LogOnReorg | CustomReorgAction;

export type OnReorgConfig = {
  action: OnReorgOptions;
  depth: number;
};

export interface TransactionConfirmation {
  // this the number of block confirmations before we resolve the promise
  // i.e. "wait 5 blocks before proceeding to the next step in my task"
  confirmations?: number;
  onReorg?: OnReorgConfig;
}

export interface IWallet {
  readonly name: string;
  readonly address: Address;
  writeContract(
    chain: Chain,
    contractAddress: Address,
    functionSig: string,
    args: unknown[],
    confirmation?: TransactionConfirmation,
    retryConfig?: ContextFunctionRetryConfig,
  ): Promise<{
    hash: string;
    receipt: TransactionReceipt;
    userOpHash?: string; // set for gas-sponsored transactions (ERC-4337)
  }>;
  readContract<T = unknown>(
    chain: Chain,
    contractAddress: Address,
    functionSig: string,
    args: unknown[],
    retryConfig?: ContextFunctionRetryConfig,
  ): Promise<T>;
  sendTransaction(
    config: {
      to: Address;
      data: `0x${string}`;
      chain: Chain;
      value?: bigint;
      maxFeePerGas?: bigint;
      maxPriorityFeePerGas?: bigint;
      gas?: bigint;
      nonce?: number; // EOA wallets only
    },
    confirmation?: TransactionConfirmation,
    retryConfig?: ContextFunctionRetryConfig,
  ): Promise<{
    hash: string;
    receipt: TransactionReceipt;
    userOpHash?: string; // set for gas-sponsored transactions (ERC-4337)
  }>;
  simulate(
    chain: Chain,
    contractAddress: Address,
    functionSig: string,
    args: unknown[],
    retryConfig?: ContextFunctionRetryConfig,
  ): Promise<{ hash: string }>;
  getBalance(
    chain: Chain,
    retryConfig?: ContextFunctionRetryConfig,
  ): Promise<string>; // native token balance in wei
}

export interface Log {
  address: Address;
  topics: `0x${string}`[];
  data: `0x${string}`;
  blockHash: `0x${string}`;
  blockNumber: bigint;
  logIndex: number;
  transactionHash: `0x${string}`;
  transactionIndex: number;
  removed?: boolean;
}

export interface TransactionReceipt {
  blockHash: `0x${string}`;
  blockNumber: bigint;
  contractAddress: Address | null;
  cumulativeGasUsed: bigint;
  effectiveGasPrice: bigint;
  from: Address;
  gasUsed: bigint;
  logs: Log[];
  logsBloom: `0x${string}`;
  status: "success" | "reverted";
  to: Address | null;
  transactionHash: `0x${string}`;
  transactionIndex: number;
  type: "legacy" | "eip1559" | "eip2930" | "eip4844" | "eip7702";
}

export interface OnchainEvent {
  blockNumber: number;
  blockHash: string;
  transactionIndex: number;
  removed: boolean;
  address: string;
  data: `0x${string}`;
  topics: `0x${string}`[];
  transactionHash: string;
  logIndex: number;
}

export interface FetchConfig {
  method?: string;
  headers?: Record<string, string>;
  body?: Record<string, unknown> | string;
}

export interface Logger {
  info(message: string, data?: Record<string, unknown>): void;
  warn(message: string, data?: Record<string, unknown>): void;
  error(message: string, data?: Record<string, unknown>): void;
}

export type TaskContext = {
  env: Record<string, string>;
  logger: Logger;
  callTask: <Args = Record<string, unknown>, T = unknown>(
    taskName: string,
    args: Args,
    retryConfig?: ContextFunctionRetryConfig,
  ) => Promise<T>;
  sideEffect: <T>(fn: () => T | Promise<T>) => Promise<T>;
  fetch: <T = unknown>(
    url: string,
    fetchConfigOrRetryConfig?: FetchConfig | ContextFunctionRetryConfig,
    retryConfig?: ContextFunctionRetryConfig,
  ) => Promise<T | undefined>;
  evm: {
    chains: Record<string, Chain>;
    wallet: (config: WalletConfig) => Promise<IWallet>;
    decodeEventLog: <T = unknown>(abi: Abi, log: OnchainEvent) => Promise<T>;
    contracts: Record<string, unknown>; // auto-generated from ABIs in src/contracts/
  };
  collection: <T>(
    name: string,
    indexes?: CollectionIndexSpec[],
  ) => Promise<Collection<T>>;
  turbo: {
    createPipeline: (config: CreateTurboPipelineConfig, retryConfig?: ContextFunctionRetryConfig) => Promise<TurboPipeline>;
    createJob: (config: CreateTurboJobConfig, retryConfig?: ContextFunctionRetryConfig) => Promise<TurboPipeline>;
    getPipeline: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<TurboPipeline>;
    getStatus: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<TurboPipelineStatus>;
    listPipelines: (retryConfig?: ContextFunctionRetryConfig) => Promise<TurboPipeline[]>;
    pausePipeline: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<PipelineActionResult>;
    resumePipeline: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<PipelineActionResult>;
    restartPipeline: (name: string, options?: RestartOptions, retryConfig?: ContextFunctionRetryConfig) => Promise<PipelineActionResult>;
    deletePipeline: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<PipelineDeleteResult>;
    getLogs: (name: string, options?: GetLogsOptions, retryConfig?: ContextFunctionRetryConfig) => Promise<PipelineLogsResult>;
    getState: (name: string, retryConfig?: ContextFunctionRetryConfig) => Promise<unknown>;
    validate: (definition: TurboPipelineDefinition, retryConfig?: ContextFunctionRetryConfig) => Promise<ValidateResult>;
  };
};

See the turbo reference for the full type definitions used above (TurboPipeline, TurboPipelineStatus, ValidateResult, etc.).

Logger

context.logger is a run-aware structured logger. Unlike console.log, logs emitted through context.logger are tagged with the current task name and run ID, which enables two powerful debugging workflows in the Compose dashboard:

Search app-level logs, then jump to the run — On the Logs tab of your app, you can search for a log pattern across all runs. Each matching log entry includes a “View run” link that takes you directly to the full task run, where you can see the complete OpenTelemetry trace of everything that happened in that run.
View run-specific logs — On any task run’s detail page, the Logs tab shows only logs from that specific run, making it easy to understand what happened in a single execution.

Usage

import { TaskContext } from "compose";

export async function main({ logger, evm, env }: TaskContext) {
  logger.info("Starting price update", { source: "coingecko" });

  try {
    const wallet = await evm.wallet();
    const { hash } = await wallet.writeContract(
      evm.chains.base,
      env.CONTRACT_ADDRESS as `0x${string}`,
      "setPrice(bytes32,bytes32)",
      [timestampBytes, priceBytes]
    );

    logger.info("Price updated", { hash, chain: "base" });
  } catch (error) {
    logger.error("Price update failed", {
      error: error instanceof Error ? error.message : String(error),
    });
    throw error;
  }
}

API

interface Logger {
  info(message: string, data?: Record<string, unknown>): void;
  warn(message: string, data?: Record<string, unknown>): void;
  error(message: string, data?: Record<string, unknown>): void;
}

Each method takes a message string and an optional data object for structured metadata. BigInt values (common in EVM code) are automatically serialized as strings.

`console.log` vs `context.logger`

Both console.log and context.logger output to your terminal during local development. The difference is in the cloud:

	`console.log`	`context.logger`
Appears in app-level logs	Yes	Yes
Tagged with run ID and task name	No	Yes
”View run” link in dashboard	No	Yes
Appears in run-specific Logs tab	No	Yes
Structured `data` field	No	Yes

Use console.log for quick debugging. Use context.logger when you want logs that you can trace back to a specific task run in production.

Compose

Guides

Reference

Overview

Retry Configuration

Durable execution and context caching

Overview of key context properties and functions

Full TaskContext interface

Logger

Usage

API

`console.log` vs `context.logger`

Next Steps

Fetch

Collections

​Retry Configuration

​Durable execution and context caching

​Overview of key context properties and functions

​Full TaskContext interface

​Logger

​Usage

​API

​console.log vs context.logger

​Next Steps

Fetch

Collections

Retry Configuration

Durable execution and context caching

Overview of key context properties and functions

Full TaskContext interface

Logger

Usage

API

`console.log` vs `context.logger`

Next Steps