Ditto Workflow SDK Skill

Build and deploy declarative on-chain automation workflows using @ditto/workflow-sdk. Workflows define triggers (cron, event, onchain state) and jobs (batched contract calls) that execute via ZeroDev smart accounts with session keys.

SDK source: github.com/dittonetwork/ditto-workflow-sdk (branch: skill-integration)

Architecture: Owner vs Executor

Understanding these two roles is critical:

• Owner (the client/user): Holds a private key, creates and signs workflows. This is the only key the user provides.
• Executor (Ditto Network): A decentralized network of operators that runs workflows. The client only needs the executor's public address, never its private key.

submitWorkflow takes executorAddress (a public 0x... address) — NOT a private key. The session key system grants scoped permissions to this address so the network can execute on behalf of the owner's smart account.

Critical: Before You Start

BEFORE writing any workflow code, verify the project setup:

1. Check that @ditto/workflow-sdk is installed: look for it in package.json
2. Check that a .env file exists with required keys (see Environment Setup below)
3. If the SDK is not installed, run: npm install @ditto/workflow-sdk

Environment Setup

The .env file MUST contain:

PRIVATE_KEY=0x...          # Owner's private key (the user's wallet — used to sign and deploy)
IPFS_SERVICE_URL=https://ipfs-service.dittonetwork.io

Optional (only needed for cancellation):

WORKFLOW_CONTRACT_ADDRESS=0x... # DittoWFRegistry address

The executor address is embedded in the SDK — use getDittoExecutorAddress() from @ditto/workflow-sdk. Do NOT ask the user for an executor address or private key.

CRITICAL:

• Never ask the user for an executor private key or address. The SDK provides the executor address via getDittoExecutorAddress().
• Never hardcode the owner's private key in source files. Always load from .env via dotenv.

Instructions

Step 1: Gather Requirements

Ask the user for:

• What action? (transfer ETH, swap tokens, call a contract function)
• On which chain? (see Supported Chains below)
• When/how often? (cron schedule, on event, or when a condition is met)
• How many times? (execution limit)
• Target contract address and function signature (if calling a contract)

If the user is vague, suggest a concrete workflow and confirm before proceeding.

Step 2: Write the Workflow Script

Create a TypeScript file that:

1. Loads environment variables with dotenv
2. Creates the owner account with privateKeyToAccount
3. Builds the workflow using WorkflowBuilder and JobBuilder
4. Submits with submitWorkflow, passing the executor's public address

Key pattern: WorkflowBuilder.create() takes an Account (address only, no signing capability). Use addressToEmptyAccount(owner.address) for this. The actual Signer (full private key account from privateKeyToAccount) is passed separately to submitWorkflow for signing session keys and transactions.

Minimal template:

import {
  WorkflowBuilder, JobBuilder, ChainId,
  submitWorkflow, IpfsStorage, getDittoExecutorAddress
} from '@ditto/workflow-sdk';
import { privateKeyToAccount } from 'viem/accounts';
import { addressToEmptyAccount } from '@zerodev/sdk';
import * as dotenv from 'dotenv';

dotenv.config();

async function main() {
  // Owner: full Signer (signs the workflow and session keys)
  const owner = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

  // Executor address is provided by the SDK — no user configuration needed
  const executorAddress = getDittoExecutorAddress();

  const storage = new IpfsStorage(process.env.IPFS_SERVICE_URL!);

  // WorkflowBuilder gets Account (address only), not Signer
  const workflow = WorkflowBuilder.create(addressToEmptyAccount(owner.address))
    .addCronTrigger('0 */6 * * *')  // Every 6 hours
    .setCount(10)                    // Max 10 executions
    .setValidUntil(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 days
    .addJob(
      JobBuilder.create('my-job')
        .setChainId(ChainId.BASE_SEPOLIA)
        .addStep({
          target: '0xRecipientAddress',
          abi: '',           // Empty ABI = raw ETH transfer
          args: [],
          value: BigInt(1e15) // 0.001 ETH in wei
        })
        .build()
    )
    .build();

  const { ipfsHash, userOpHashes } = await submitWorkflow(
    workflow,
    executorAddress,               // Public address, not a key
    storage,
    owner,                         // Owner signs here
    false,                         // prodContract: false = testnet
    process.env.IPFS_SERVICE_URL!,
  );

  console.log('Deployed! IPFS hash:', ipfsHash);
  console.log('Transaction receipts:', userOpHashes);
}

main().catch(console.error);

Step 3: Fund the Smart Account

IMPORTANT: The Ditto SDK uses ZeroDev smart accounts (account abstraction). The smart account address is different from the owner's EOA wallet address. It is deterministically derived from the owner's private key by the ZeroDev kernel.

When submitWorkflow runs, it registers the workflow on-chain from this smart account. The smart account must have ETH on the target chain to pay for gas.

How to find the smart account address: Run the workflow script — if underfunded, the error message will include the smart account address (e.g., AA21 didn't pay prefund). Alternatively, add this before submitWorkflow:

import { signerToEcdsaValidator } from '@zerodev/ecdsa-validator';
import { createKernelAccount } from '@zerodev/sdk';
import { createPublicClient, http } from 'viem';
import { getChainConfig } from '@ditto/workflow-sdk';

const chainConfig = getChainConfig(process.env.IPFS_SERVICE_URL!);
const chain = chainConfig[ChainId.BASE_SEPOLIA]; // use your target chain
const publicClient = createPublicClient({ chain: chain.chain, transport: http(chain.rpcUrl) });
const ecdsaValidator = await signerToEcdsaValidator(publicClient, { signer: owner, entryPoint: { address: '0x0000000071727De22E5E9d8BAf0edAc6f37da032', version: '0.7' } });
const kernelAccount = await createKernelAccount(publicClient, { plugins: { sudo: ecdsaValidator }, entryPoint: { address: '0x0000000071727De22E5E9d8BAf0edAc6f37da032', version: '0.7' } });
console.log('Smart account address (fund this):', kernelAccount.address);

Funding:

• Testnet: Use a faucet (e.g., Sepolia faucet, Base Sepolia faucet) to send test ETH to the smart account address
• Production: Send real ETH (0.005–0.01 ETH is typically enough for gas) to the smart account address on the target chain

CRITICAL: Always recommend testnet first. Only proceed to production chains after the user has verified the workflow works on testnet.

Step 4: Run and Verify

npx ts-node your-workflow-script.ts

Expected output: IPFS hash and transaction receipt(s). The Ditto Network will now automatically execute this workflow according to the triggers. If submission fails, check the Troubleshooting section.

Supported Chains

Testnet (use for development):

Production:

Note: ChainId.HOLESKY (17000) exists in the enum but is deprecated and should not be used for new workflows.

CRITICAL: NEVER deploy to production chains (Base, Arbitrum, Polygon, Optimism, Mainnet) without explicit user confirmation. Always default to testnet. When deploying to production, set prodContract: true in submitWorkflow.

Trigger Types

Cron Trigger (time-based)

.addCronTrigger('*/5 * * * *')  // Every 5 minutes (UTC)

Event Trigger (log-based)

.addEventTrigger({
  chainId: ChainId.SEPOLIA,
  contractAddress: '0xTokenAddress',
  signature: 'Transfer(address,address,uint256)',
  filter: { from: '0xSpecificSender' }  // Optional: filter indexed params
})

Onchain Trigger (state-based)

import { OnchainConditionOperator } from '@ditto/workflow-sdk';

.addOnchainTrigger({
  chainId: ChainId.BASE,
  target: '0xOracleAddress',
  abi: 'latestAnswer() view returns (int256)',
  args: [],
  onchainCondition: {
    condition: OnchainConditionOperator.GREATER_THAN,
    value: 200000000000n  // e.g., ETH > $2000 (8 decimals)
  }
})

Multiple triggers are AND-ed: all must be satisfied for execution.

OnchainConditionOperator values: EQUAL (0), GREATER_THAN (1), LESS_THAN (2), GREATER_THAN_OR_EQUAL (3), LESS_THAN_OR_EQUAL (4), NOT_EQUAL (5), ONE_OF (6).

Key Operations

Simulate (dry run)

Simulation is typically performed by the Ditto Network operators, not by clients. If you need to simulate locally for debugging, use executeFromIpfs with simulate: true — but note this requires an executor account with signing capability (for local testing only).

Cancel a Workflow

import { WorkflowContract } from '@ditto/workflow-sdk';

const wfContract = new WorkflowContract(process.env.WORKFLOW_CONTRACT_ADDRESS as `0x${string}`);
await wfContract.cancelWorkflow(ipfsHash, ownerAccount, chainId, process.env.IPFS_SERVICE_URL!);

Check Workflow Status & Execution History

Use the Ditto Network API (base URL: https://ipfs-service.dittonetwork.io) to monitor deployed workflows. All endpoints use the IPFS hash returned by submitWorkflow. No authentication required.

1. Workflow status — check if the workflow is active, paused, or cancelled:

const ipfsHash = 'QmYourWorkflowHash';
const res = await fetch(`https://ipfs-service.dittonetwork.io/workflow/status/${ipfsHash}`);
const status = await res.json();
console.log('Workflow status:', status);

2. Execution logs (USE THIS to check last executions) — returns the actual execution history with results, timestamps, and transaction details:

const res = await fetch(`https://ipfs-service.dittonetwork.io/workflow/logs/${ipfsHash}?limit=20`);
const logs = await res.json();
console.log('Execution logs:', logs);

This is the primary endpoint for checking whether a workflow has run, when it ran, and whether executions succeeded or failed.

3. Execution reports (advanced — NOT for checking execution history) — these are internal simulation reports sent by all network operator nodes participating in the workflow. Each operator independently simulates the workflow, so you'll see multiple reports per execution (one per node). This is useful for debugging network-level issues but NOT for checking whether your workflow actually executed:

const res = await fetch(`https://ipfs-service.dittonetwork.io/get-reports?ipfsHash=${ipfsHash}&page=1&limit=100`);
const reports = await res.json();
console.log('Node simulation reports:', reports);

IMPORTANT: When the user asks to "check last executions" or "see execution history", always use the execution logs endpoint (/workflow/logs/), NOT the reports endpoint. Reports show per-node simulation data, not actual execution outcomes.

Data References (read contract state at execution time)

import { dataRef } from '@ditto/workflow-sdk';

const ethPrice = dataRef({
  target: '0xChainlinkOracleAddress',
  abi: 'latestRoundData() returns (uint80, int256, uint256, uint256, uint80)',
  chainId: ChainId.SEPOLIA,
  resultIndex: 1,  // int256 price is the 2nd return value
});

// Use in a step arg - resolved dynamically at execution time by the network
.addStep({
  target: '0xSwapRouter',
  abi: 'swap(uint256)',
  args: [ethPrice],
})

Workflow Limits

Step Interface

interface Step {
  target: string;              // Contract address (0x-prefixed)
  abi: string;                 // Function signature, e.g. "transfer(address,uint256)"
                               // Empty string "" for raw ETH transfer
  args: readonly any[];        // Function arguments (can include dataRef strings)
  value?: bigint | string;     // ETH value in wei
}

Key Function Signatures

submitWorkflow

async function submitWorkflow(
  workflow: Workflow,
  executorAddress: `0x${string}`, // Public address of the Ditto Network executor
  storage: IWorkflowStorage,
  owner: Signer,                  // Owner signs (from privateKeyToAccount)
  prodContract: boolean,          // true = mainnet registry, false = testnet
  ipfsServiceUrl: string,
  usePaymaster?: boolean,         // Default: false
  switchChain?: (chainId: number) => Promise<void>,
  accessToken?: string,
): Promise<{ ipfsHash: string; userOpHashes: UserOperationReceipt[] }>;

executeFromIpfs (used by network operators, not clients)

async function executeFromIpfs(
  ipfsHash: string,
  storage: IWorkflowStorage,
  executorAccount: Signer,    // Executor's Signer — held by network operators only
  prodContract: boolean,
  ipfsServiceUrl: string,
  simulate?: boolean,
  usePaymaster?: boolean,
  accessToken?: string,
): Promise<{ success: boolean; results: any[] }>;

Multi-Chain Workflows

A workflow can have multiple jobs on different chains:

.addJob(
  JobBuilder.create('job-sepolia')
    .setChainId(ChainId.SEPOLIA)
    .addStep({ /* ... */ })
    .build()
)
.addJob(
  JobBuilder.create('job-base')
    .setChainId(ChainId.BASE)
    .addStep({ /* ... */ })
    .build()
)

Each job gets its own session key and on-chain registration.

Multi-Step Job (Approve + Swap)

Steps within a single job execute atomically:

JobBuilder.create('weekly-dca')
  .setChainId(ChainId.BASE)
  .addStep({
    target: tokenAddress,
    abi: 'approve(address,uint256)',
    args: [routerAddress, amount],
  })
  .addStep({
    target: routerAddress,
    abi: 'swapExactTokensForETH(uint256,uint256,address[],address,uint256)',
    args: [amount, 0, [tokenAddress, wethAddress], owner.address, deadline],
  })
  .build()

Note: Time-dependent args like deadline are computed at script build time, not execution time. For workflows that may execute later, use generous deadlines or dataRef for on-chain timestamps.

Validation Checklist

BEFORE calling submitWorkflow, verify:

• Every step has a valid target address (0x-prefixed, 42 chars)
• abi is a valid Solidity function signature or empty string for raw ETH transfer
• chainId is from the supported chains list
• At least one trigger is defined
• count is > 0 if set
• validUntil is in the future
• .env has PRIVATE_KEY and IPFS_SERVICE_URL

Troubleshooting

Error: "Missing required environment variables"

Cause: .env file missing or incomplete. Solution: Ensure PRIVATE_KEY and IPFS_SERVICE_URL are set. The executor address is provided by the SDK via getDittoExecutorAddress() — do NOT add it to .env.

Error: "Chain ID must be greater than 0"

Cause: setChainId() not called on JobBuilder. Solution: Add .setChainId(ChainId.BASE_SEPOLIA) before .build().

Error: "Job must have at least one step"

Cause: No steps added to a job. Solution: Add at least one .addStep({...}) call.

Error: "Expiration time must be in the future"

Cause: setValidUntil was given a past timestamp. Solution: Use Date.now() + duration_in_ms.

Error: "AA21 didn't pay prefund"

Cause: The ZeroDev smart account doesn't have enough ETH to pay for gas. The smart account address is different from the owner's EOA — it's derived deterministically from the owner's private key. Solution: Send ETH to the smart account address shown in the error on the target chain. See "Step 3: Fund the Smart Account" above. For testnet, use a faucet. For production, 0.005–0.01 ETH is typically enough.

Transaction fails / reverts

Causes:

• Smart account has insufficient ETH for the step values
• Target contract function reverts (wrong args, permissions)
• Session key expired or misconfigured

Solution: Ensure the owner's smart account is funded on the target chain. Verify contract args are correct.

IPFS upload fails

Cause: IPFS_SERVICE_URL unreachable or invalid. Solution: Verify the URL is correct and accessible. Default: https://ipfs-service.dittonetwork.io