Add ACP serve provider runtime

[ai-virtual-b]

Summary

• add acp serve scaffolding/start/endpoints/deploy commands for provider service jobs
• use BE-mediated public x402/MPP endpoints while the provider runtime handles payment challenges, verification, settlement, and handler execution over the service-jobs relay
• add Railway deploy packaging, Cloudflare placeholder provider, deploy signer/keychain support, and direct x402/MPP payment helpers using @x402 and mppx
• keep --settle-8183 reserved/disabled until contract support is available

Verification

• npm run build
• npx tsc --noEmit --module es2022 --target es2022 --moduleResolution bundler --strict --esModuleInterop --skipLibCheck --types node serve/server/relay.ts serve/server/payment/chain.ts serve/server/payment/x402.ts serve/server/payment/mpp.ts

Notes

• This pairs with Virtual-Protocol/agentic-commerce-be#100. The backend owns public URLs and job persistence; this CLI runtime owns x402/MPP challenge + settlement.

---

Note

High Risk
Adds a new provider runtime that verifies and settles x402/MPP payments and introduces deploy-signer key handling, which is security- and funds-sensitive despite being largely additive. Also refactors agent signer setup and offering creation flows, which could impact onboarding and publishing behavior if misconfigured.

Overview
Introduces acp serve to scaffold, run, and deploy offering-backed provider runtimes that execute a developer handler.ts and optionally budget.ts, supporting ACP-native jobs plus BE-mediated x402/MPP service jobs over a Socket.IO relay.

Adds payment verification/settlement helpers for x402 (EIP-3009) and MPP, a sandboxed handler execution mode (worker thread with empty env), and deploy bundling/providers (Railway end-to-end, Cloudflare placeholder) that package a runnable bundle and optionally drive the Railway CLI.

Updates CLI/docs to reflect buyer/seller terminology and new env vars, adds offering privacy + offering create --from-file (writing back assigned IDs), and changes agent signer setup to generate/store P256 keys in keychain and enable automatic signer setup gated by ACP_PRIVY_APP_ID.

^{Reviewed by Cursor Bugbot for commit a844e87. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a844e87. Configure here.}

[cursor]

Truncated USDC address for Base mainnet

High Severity

The USDC address for Base mainnet is truncated to 36 hex digits instead of the required 40. The value "0x833589fCD6E08f4c7C32D4f71b54bdA02913" is missing the eDb6 segment — the correct address is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. This invalid address will cause all x402/MPP payment operations on Base mainnet (chain 8453) to fail or interact with the wrong contract.

 

^{Reviewed by Cursor Bugbot for commit a844e87. Configure here.}

[cursor]

Private key reused as MPP HMAC secret

Medium Severity

getSecretKey() falls back to ACP_SIGNER_PRIVATE_KEY — the provider's on-chain settlement private key — as the HMAC secretKey for MPP challenge generation. Reusing a blockchain signing key as a symmetric secret for a different cryptographic protocol increases key exposure and violates key separation principles. A hardcoded fallback "acp-local-mpp-secret" also exists, which is predictable in production if no env vars are set.

 

^{Reviewed by Cursor Bugbot for commit a844e87. Configure here.}

[ai-virtual-b]

Closing as duplicate. The provider-runtime settlement changes have been pushed to existing PR #9: #9