Incorporate Starknet into examples/facilitator-server with TDD coverage

[ponderingdemocritus]

Summary

Incorporate Starknet as a fully documented, test-enforced path in examples/facilitator-server, using the already-implemented core Starknet support.

Core Starknet primitives already exist in packages/core; this issue focuses on example server integration hardening, CI coverage, and docs quality.

Why

examples/facilitator-server already wires Starknet in setup, but the integration is implicit and under-tested. This makes regressions likely when touching setup, /supported normalization, or env handling.

Scope

• In scope: examples/facilitator-server tests, setup behavior validation, docs/comments, CI assertions.
• Out of scope: new Starknet protocol implementation in core, Starknet upto, production mainnet settlement automation.

Requirements

• Starknet remains opt-in via STARKNET_NETWORKS.
• Missing sponsor address must fail fast with actionable error.
• /supported must expose Starknet kinds, extra.paymasterEndpoint, extra.sponsorAddress, and signers["starknet:*"].
• Preserve EVM/SVM behavior.

Detailed Task List

1) Add Starknet /supported test coverage (TDD first)

• Create examples/facilitator-server/tests/starknet-supported.test.ts.
• Add a RED test asserting Starknet kind(s) appear in /supported when Starknet configs are registered.
• Add a RED test asserting Starknet extra.paymasterEndpoint and extra.sponsorAddress are present.
• Add a RED test asserting sponsor appears in supported.signers["starknet:*"].
• Add a RED test asserting Starknet remains canonical CAIP (starknet:SN_*) and x402 v2.
• Run test file and capture failing output before code changes.

2) Make minimal setup/app changes to pass tests

• Update examples/facilitator-server/src/setup.ts only as needed to satisfy failing tests.
• Confirm no regressions in EVM/SVM setup paths.
• Keep changes minimal; no broad refactor during GREEN.

3) Add Starknet config validation tests

• Create examples/facilitator-server/tests/starknet-config-validation.test.ts.
• Add test for deterministic failure when sponsor env is missing for enabled Starknet network.
• Add test for documented skip/fail behavior when Starknet RPC or paymaster endpoint is unresolved.
• Run tests and verify failure reasons match intended behavior (missing feature vs test bug).

4) Add CI/runtime assertion for Starknet-enabled boot path

• Extend examples/facilitator-server/tests/e2e-ci.ts (or add a dedicated Starknet e2e script).
• Boot built server with Starknet env vars set to deterministic test values.
• Assert /supported includes expected Starknet network entry.
• Keep test independent from live on-chain settlement.

5) Documentation and operator guidance

• Update facilitator-server-facing docs/comments for Starknet env vars:
  • STARKNET_NETWORKS
  • STARKNET_RPC_URL_STARKNET_MAINNET
  • STARKNET_RPC_URL_STARKNET_SEPOLIA
  • STARKNET_PAYMASTER_ENDPOINT_STARKNET_MAINNET
  • STARKNET_PAYMASTER_ENDPOINT_STARKNET_SEPOLIA
  • STARKNET_PAYMASTER_API_KEY (+ per-network overrides)
  • STARKNET_SPONSOR_ADDRESS (+ per-network overrides)
• Add a minimal local run example for Starknet-enabled facilitator-server.
• Ensure Docker/example notes do not imply Starknet is auto-enabled.

6) Regression safety and completion

• Run cd examples/facilitator-server && bun run test.
• Run cd examples/facilitator-server && bun run build.
• Run cd examples/facilitator-server && bun run test:e2e.
• Verify no existing tests fail due to Starknet additions.

Acceptance Criteria

• Starknet integration is covered by explicit tests in examples/facilitator-server/tests.
• /supported returns Starknet metadata (paymasterEndpoint, sponsorAddress) and signer list when enabled.
• Startup/config failure behavior for missing Starknet sponsor is deterministic and actionable.
• CI covers Starknet-enabled server boot path without requiring live settlement.
• EVM/SVM behavior remains unchanged.

Implementation Notes

• Follow strict Red -> Green -> Refactor workflow.
• Keep library/application separation intact (packages/core remains side-effect-free library code).
• Use package imports in examples (no relative imports to core internals).

Source

Derived from: docs/prd-starknet-facilitator-server.md