Skip to content

Add canonical v2 APIs and mutable read streams - #411

Draft
rotilho wants to merge 1 commit into
mainfrom
codex/v2-streams-and-canonical-addresses
Draft

rotilho wants to merge 1 commit into
mainfrom
codex/v2-streams-and-canonical-addresses

Conversation

@rotilho

@rotilho rotilho commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Expose Commons 10 canonical address models through the v2 HTTP API and public /v2/stream WebSocket endpoint, with shared query owners for both transports.

  • V2 JSON uses owner and role addresses plus decimal-string amounts, heights, and timestamps; duplicate public-key/address-algorithm fields are removed. V2 transaction publication requires canonical identities. Existing legacy HTTP routes retain their original identity fields, numeric values, and key-only publication input compatibility. Supplied canonical fields take precedence over duplicate legacy input.
  • Add finite POST /v2/accounts lookup and one-second blank-line heartbeats on v2 NDJSON streams. Legacy streams remain heartbeat-free. Transaction publication stays on HTTP at POST /v2/transactions with its existing confirmation deadline.
  • Support all 13 read stream operations over WebSocket, including mutable membership for four multi-account streams, acknowledgements, bounded delivery, and cancellation. Account, entry, transaction, and receivable query components own the snapshot/live handoff used by HTTP and WebSocket adapters.
  • Extract peer challenge authentication into HandshakeProtocol, preserving one-time consumption and transport-owned admission/deadlines. Consolidate each election voter's candidate, latest timestamp, and stability timestamp into one immutable state. Move query tests with their owners and update the runtime maps.
  • Upgrade Commons to 10.0.0-SNAPSHOT and Spring Boot to 4.1.2.

Validation passed on the exact signed PR snapshot with Java 25: all 515 tests, full ktlintCheck, and bootJar. Coverage includes query handoff/cancellation, HTTP/OpenAPI and legacy compatibility, mutable WebSocket streams, handshake behavior, and voter-state transitions. After the shared server cancellation fix, all 20 targeted stream/HTTP boundary checks, full ktlintCheck, and bootJar passed against the fixed module. The rebuilt Node JAR and pinned integration image contain that exact reviewed server artifact; application sources are unchanged. The released-live neighbour suite was not rerun; legacy HTTP compatibility is covered by real socket tests using frozen released payloads.

This change depends on publication of the matching Commons 10 artifacts; the current development snapshot is not published remotely. Upgrade remote signers before enabling these canonical Node requests, then deploy this Node before Gatekeeper or clients requiring its v2 APIs. Wallet-server migration and production rollout remain separate work.

Independent Astra Max review covered the complete 122-path PR diff with no actionable findings. An additional packaged-decoder probe passed 82 canonical and legacy input cases.

Related PRs: Commons, Gatekeeper, Signer.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant