Ditto Workflow

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!);