Workflow Engine

A multi-step operation, such as an asset deployment or a corporate action, recovers from a crash without repeating a step it already finished. The engine stores each activity's result and reuses it on replay. Work whose result was not recorded runs again.

The engine tracks a run as running, waiting, suspended, completed, or failed. A run enters waiting for an approval, a threshold, or a timer with a deadline the operation defines, and suspended when an infrastructure retry sequence is exhausted and awaits automatic recovery.

On-chain writes still use the Transaction QueueThe transaction queue lets an integrator submit a blockchain write once and retry it safely, without ever risking a duplicate broadcast to the chain.Read the concept for deduplication and sequencing. Durable execution alone does not make external effects happen exactly once.

Why a multi-step operation needs durable executionCopy Anchor Link

An operation such as deploying an asset, processing a corporate action, or approving a batch of identity claims is never one call. It chains several steps, each one a separate effect: a custody signature, an on-chain write, a compliance check, sometimes a wait for a threshold or an approval. If the process running that chain restarts before it finishes, nothing outside the platform can tell which of those effects already happened.

A naive retry gets this wrong in one of two directions. Restarting the whole operation can resubmit a step that already reached the chain, so an asset deploys twice or a claim is minted twice. Resuming from wherever the process happens to pick back up can skip a step that never ran, so a required compliance check is silently missing from an operation the caller believes is complete. Both mistakes are invisible from outside: the caller sees only that the operation eventually reports a result, not whether its internal steps produced that result honestly.

Asset Lifecycle names a related risk at the boundary between systems, a reconciliation where an instrument's ledger state and its legal record drift apart. The Workflow Engine closes a narrower gap: it keeps the steps inside one multi-step operation from running twice or from silently not running at all after a restart.

Why one recovery layer serves every operation, not one per domainCopy Anchor Link

The alternative is for each kind of operation to carry its own recovery logic. One retry scheme serves an asset deployment, a different one a corporate action, and a third a batch of identity claims. Each scheme would answer the same question, whether a given step already ran, in its own way. A platform with as many answers as it has operation types makes recovering an operation depend on which team wrote its retry code.

The Workflow Engine is shared machinery instead. One execution record and one replay rule serve every domain that runs a multi-step operation, whether it deploys an asset, provisions a custody wallet, or processes a corporate action. An integrator reads the same kind of status and the same kind of recorded evidence whatever operation they started, because the recovery layer underneath does not change.

What the engine records, and what replay does with itCopy Anchor Link

The engine records each activity's result as it completes. A restarted process replays the workflow's code from the top, but a completed activity returns its stored result instead of running its work again. An activity interrupted before its result was saved executes again.

Replay only guarantees the workflow's own bookkeeping. It says nothing about the business outcome of an external effect, so external effects still need their own duplicate protection, including writes submitted through the Transaction Queue. A stored result does not prove every business outcome was successful. Read the operation's result and any failure details before reporting success.

Running, waiting, and suspended are different statesCopy Anchor Link

A running workflow executes its next activity. Waiting means the operation needs a condition such as an approval, funds, or a timer. It can continue when that condition is satisfied. A deadline can end a wait, but the workflow decides what happens when the deadline expires.

Suspended means an infrastructure failure exhausted the activity's immediate retries. The platform schedules another recovery attempt with backoff. Automatic recovery is bounded. Persistent failure can end the run as failed. Restore the unavailable dependency when an incident prevents progress.

Completed and failed are terminal workflow statuses. They describe the workflow's outcome. Waiting and suspended are non-terminal. Status projections can lag during a database outage, so a stale running status does not prove that an activity is still executing.

When an operation pauses for fundsCopy Anchor Link

An operation configured to wait for gas funding pauses the affected step when the paying wallet has insufficient funds. The work recorded before that step remains available for replay. The funding request identifies the wallet or deposit to fund, the required amount, and the deadline.

The amount required to retry the refused operation controls when it can resume. The operator may also see an estimate for the remaining work. That estimate helps plan funding but does not raise the resume threshold.

Fund the destination shown in the request. An ordinary signing account or a self-funded smart account uses an address balance. A paymaster uses its deposit in the EntryPoint contract. Funding the paymaster address alone does not increase that deposit.

A balance observation and a transaction broadcast can use different network nodes. A deposit visible to one node may take time to reach another. The platform makes bounded broadcast retries after funding. A repeated rejection does not always mean another deposit is needed.

When the funding deadline expires, read the recorded error, fund the requested destination, and start a new attempt as the operation's API specifies. Operations that do not enable the funding pause fail with GAS_REQUIRED, which identifies the funding shortfall.

The engine and the API run separatelyCopy Anchor Link

The API hands durable work to the Workflow Engine, which runs in a separate process. The engine uses database-backed execution records to recover after a restart. Its availability and capacity can therefore differ from the API's: an accepted request can remain in progress while the engine recovers.

Follow the operation's status contractCopy Anchor Link

An asynchronous start returns an operation identifier or status link. Acceptance means the platform accepted the request for processing. It does not mean the operation finished. Use the status endpoint returned by that operation and interpret its documented states.

After a lost response, inspect the original operation before sending another request. Repeat the API request with the same Idempotency-Key only when its route documents replay safety. At the workflow boundary, reusing the key does not create a fresh attempt after a terminal failure. Correct the failure's cause before starting a new business attempt with a new key.

A client polls until the operation reaches a documented terminal state. Read the resulting resource after success. A pending operation does not yet promise that a separate resource read contains its changes.

For operational monitoring, the Console's Platform Health view includes workflow status. That view complements the status endpoint used by the integration. It does not replace the operation's result.

Recovery records and audit evidenceCopy Anchor Link

The execution journal records activity results needed for recovery. It has a retention policy and does not replace the platform's Audit TrailAn audit trail lets you show a regulator or an auditor who did what, under which role, without relying on the requester's own account of the request.Read the concept, the append-only record of who did what and when, or your compliance archive. Retain the operation identifier, transaction references, approvals, and other evidence your policy requires.

A workflow's recorded decision also does not prove that a token transfer passed compliance. The token's transfer checks decide whether its balances may change. Read the write's Settlement VerdictA Settlement Verdict lets you report success only when an operation actually happened, not from acceptance alone, across four recorded end states.Read the concept, the typed terminal outcome recorded for that on-chain write, to establish the on-chain outcome.

A failed workflow exposes error information through its operation's status contract. Read the error code and retry guidance before deciding whether to change the request, restore a dependency, or escalate.

Frequently asked questionsCopy Anchor Link