OutLayer Coordinator

Gate-first wallet workflow coordinator for OutLayer.

This service implements the first executable sequential NEAR Intents lane: OutLayer implicit wallet -> signed NEP-413 Intents payloads -> NEP-366 delegates -> gate.sequential.near -> ordered receipt evidence.

This is the first production coordinator slice for the mainnet dust proof. It is not a full historical coordinator restoration, and it intentionally leaves direct-user setup/execution for a later lane.

Endpoints

• POST /wallet/v1/sequential-batch
• GET /wallet/v1/sequential-batch/{request_id}
• POST /wallet/v1/workflows/plan
• POST /wallet/v1/workflows/execute
• GET /wallet/v1/workflows/{request_id}
• POST /wallet/v1/direct-user/function-call-key/prepare
• GET /wallet/v1/direct-user/function-call-key/status
• POST /wallet/v1/direct-user/function-call/execute
• GET /wallet/v1/direct-user/function-call/{request_id}

Wallet calls authenticate with either:

• X-Wallet-Id plus X-Internal-Wallet-Auth for worker/WASI calls.
• Authorization: Bearer wk_... for configured wallet API keys.

Workflow Behavior

Planner lanes:

• gate_proxy: executable in this service for intents.transfer, intents.swap, intents.execute_raw, and explicit proxy-safe sequential calls.
• funding_setup: planned but returned as requires_funding_setup; wrap, storage, deposits, and balance reads still run through existing wallet routes.
• direct_user: planned but returned as requires_direct_user_setup; true predecessor execution is a later milestone.
• reject: ambiguous or predecessor-sensitive gate calls fail before policy checks or signing.

The direct-user counter proof is the only executable direct-user lane in this branch. It is scoped to mike.near signing count.mike.near::increase with a FunctionCall access key derived from the mike.sequential.near namespace.

Gate execution:

1. Persist the idempotency record before signing or broadcasting.
2. Policy-check every gate step.
3. Build/sign NEP-413 Intents payloads for intents.near.execute_intents.
4. Ask keystore for one NEP-366 delegate per call.
5. Submit gate.submit_intent asynchronously with the relayer.
6. Poll only outer submit receipts for intent_submitted.
7. Call resume_batch_chained(intent_ids) with the approver and configured fee.
8. Poll dispatch outcomes and return ordered evidence.

Returned records include proxy_predecessor, predecessor_model, ordering_model, signed payload/delegate material, submit hashes, ordered intent IDs, resume hash, dispatch receipts, block heights, final status, and user-visible errors.

Service Boundaries

External calls:

• Keystore /wallet/derive-address to resolve the OutLayer implicit wallet.
• Keystore /wallet/check-policy before any signing.
• Keystore /wallet/sign-nep413 and /wallet/sign-nep366-delegate for gate execution.
• Keystore /wallet/direct-user/prepare-function-call-key and /wallet/direct-user/sign-scoped-function-calls for the counter proof.
• NEAR RPC for block height, async transaction broadcast, outer submit receipt polling, dispatch outcome polling, direct-user access-key checks, counter reads, final transaction evidence, and read-only gate preflight.

The read-only preflight helper queries gate owner, approver, relayer whitelist, pending count, and the 1-3 call fee tier. It does not broadcast.

Idempotency

The database enforces one record per (wallet_id, idempotency_key). A retry with the same body returns the same request record and evidence. A retry with a different body for the same key returns conflict. If callers omit an idempotency key, the service generates a server-side one for a one-shot request.

Mainnet Boundary

This service can perform real gate submissions when configured with live relayer and approver keys. Tests do not broadcast. Human operators still handle deployment, service restart, Docker, secrets, account funding, and any mainnet broadcast approval.

Configuration

Required environment:

• DATABASE_URL
• INTERNAL_WALLET_AUTH_TOKEN
• KEYSTORE_URL
• KEYSTORE_AUTH_TOKEN
• RELAYER_ACCOUNT_ID
• RELAYER_SECRET_KEY
• APPROVER_ACCOUNT_ID
• APPROVER_SECRET_KEY

Optional environment:

• BIND_ADDR, default 0.0.0.0:8080
• WALLET_API_KEYS_JSON, JSON object of API key to wallet ID
• NEAR_RPC_URL, default https://rpc.mainnet.near.org
• SEQUENTIAL_GATE_ID, default gate.sequential.near
• GATE_FEE_1_TO_3_YOCTO, default 30000000000000000000000
• SUBMIT_INTENT_GAS, default 50000000000000
• RESUME_BATCH_GAS, default 100000000000000
• DELEGATE_VALIDITY_BLOCKS, default 180
• NEAR_POLL_TIMEOUT_SECS, default 60
• NEAR_POLL_INTERVAL_MS, default 750
• INTENTS_DEADLINE_SECS, default 300

Database

Run migrations before starting the service:

sqlx migrate run

The first migration creates wallet_workflow_records, keyed by (wallet_id, idempotency_key), with JSON fields for original request, workflow spec, plan evidence, signed payloads, delegates, direct signed transactions, transaction hashes, intent IDs, dispatch evidence, direct-user scope/evidence, final status, and user-visible errors.

Checks

cargo fmt
cargo clippy --all-targets -- -D warnings
cargo test
SQLX_OFFLINE=true cargo check
git diff --check