Workflow Engine

Overview

The Workflow Engine is the DALP layer that turns an accepted lifecycle request into durable platform work. It hosts workflow-runtime-backed services covering asset operations, identity, smart-wallet routing, bundler submission, and approval management. Reconciliation jobs, webhook delivery, and exchange-rate refresh also run on the same host.

Read this page when you need to understand where long-running work is coordinated and where that scope ends. It does not replace the API reference, the transaction signing flow, custody-provider setup, or operational runbooks.

Why DALP needs durable workflows

Asset lifecycle requests can cross API validation, wallet routing, custody approval, EVM transaction submission, receipt confirmation, and Ledger Index catch-up before they become visible state. Local validation finishes quickly. Provider approval, quorum sign-off, and on-chain confirmation can take much longer.

The Workflow Engine keeps those steps out of a single HTTP request lifecycle. Accepted work is journaled as workflow progress, and you receive an immediate pending result while the engine continues through approval, broadcast, confirmation, or a terminal failure.

Architecture model

The Workflow Engine starts a workflow runtime endpoint, binds DALP workflow services, and registers that address when auto-registration is enabled. It then starts recurring background jobs: monitoring and reconciliation tasks, plus exchange-rate refresh. The HTTP health server is available before asynchronous startup completes, so health checks pass while telemetry and the durable runtime finish bootstrapping.

What the engine coordinates

Workflow patterns

Persisted workflow state

The transaction execution workflow stores status phases as submitting, awaiting-approval, confirming, completed, blocked, or failed. Its shared status read returns the current phase, transaction id, and error message when one is present.

The engine uses workflow-runtime journaled steps for operations that must survive replay. For example, provider type resolution, contract validation, state transitions, approval waits, and confirmation checks run inside workflow context rather than relying only on process memory.

Terminal and retryable failures

DALP distinguishes terminal workflow faults from transient infrastructure problems. The retry helper rethrows terminal errors immediately and retries other runtime client errors with fixed backoff. The execution path uses terminal errors for validation and policy outcomes that must not be treated as temporary platform outages.

When a smart-wallet user operation cannot proceed because the queue is blocked, DALP records a blocked outcome with BLOCKED_BY_QUEUE. Other failed queue outcomes move the entry to a failed state. Pre-broadcast terminal failures can move a transaction into a dead-letter state so it does not remain stuck in preparation or signing. You can identify the specific cause from the error state on the transaction record.

Approval and confirmation continuity

Routes with external approval can return a pending marker before the workflow completes. A smart-wallet multisig route yields a pending result while a follow-up approval workflow owns on-chain submission. A sign-only provider route signals pending policy approval while the engine waits for the approved signed transaction, then broadcasts it and waits for confirmation.

After broadcast, the engine starts confirmation monitoring and checks the transaction receipt. When a confirmed receipt includes a block number, DALP can wait for the Ledger Index to catch up before marking asynchronous consumers as completed. If your build depends on freshly indexed state, treat on-chain confirmation and Ledger Index availability as two separate signals you poll independently.

Virtual objects for serialized work

Long-running sender state is serialized through workflow runtime virtual objects. The transaction processor owns per-sender and per-chain processing for nonce-sensitive direct EVM transactions. Other bound services (bundler, monitoring, reconciliation, approval) each use their own service keys for the state they own.

Virtual objects reduce the need for application-level distributed locks, but their scope is limited to the keyed state they own. They do not replace custody policy, database consistency checks, or on-chain finality. Keep that boundary in mind when you design retry and recovery flows.

Replay-safe logging and compensation

The durable package adds replay context to logs so replayed handler attempts can be tagged with invocation metadata and duplicate log lines are suppressed during journal replay. DALP also has a saga helper for workflows that need rollback on failure: successful steps register undo handlers, and a fault runs those handlers in reverse.

Treat those patterns as architecture signals, not as a blanket promise that every workflow has a rollback path. When you integrate a workflow, check its reference page for terminal states, the cleanup behavior, and what the caller should expect.

Operational visibility

The engine emits OpenTelemetry metrics under the dalp.ddwf meter. The metric set includes:

Stall detection is query-time logic. A workflow invocation is stalled when it has been pending beyond the configured threshold and has not mutated state beyond the no-mutation threshold. The worker samples runtime admin query data when the OpenTelemetry exporter observes the gauge. It does not keep a long-lived in-process cache, so you always see fresh data at query time.

What this does not mean

See also

• Architecture overview for the platform control model
• Advanced accounts concept for the smart-account execution route and why execution stays separate from identity and policy
• Transaction Signer for signer routes, custody approval, nonce controls, and confirmation behavior
• Contract Runtime for typed contract reads, writes, and transaction construction
• Console for the human operator surface above the execution layer
• API error reference for durable execution dependency errors exposed through the public API