Tenant API: the add-hosts prepare and onboard endpoints

[schronck]

Stacked on #379. Base is feat/external-party/add-hosts-topology, so review that first — the diff here is only this commit.

Item 3 of the scoping study's §06. #379 built the serial-N+1 topology write and its validator; nothing called them. These are the callers.

Endpoints

Endpoint	Does
POST /v0/tenant/add-hosts/prepare	Reads head state, builds the serial N+1 replace, returns it with the hashes to sign
POST /v0/tenant/add-hosts/onboard	Validates the wallet-signed bundle, co-signs with this node's topology key, submits

Same shape as onboarding: every host prepares independently, the wallet compares the bytes before it signs, and each host submits only its own authorization. Canton accumulates the rest and promotes the mapping when the last one lands. No host relays to another, and a retry converges because re-submitting an identical transaction is a no-op.

Status codes worth arguing about

409 on a stale pin. Prepare reads head state before it builds. If the wallet's base_serial no longer matches, that is not a malfunction — the party moved between the wallet's read and this call — so it returns 409 with both serials and the wallet can re-read and retry. A 500 would read as "this host is broken" and send the wallet to the wrong remedy.

400 when validation refuses the bundle. validate_add_hosts_topology rejecting a submission means the caller's bytes failed against this host's own head-state read. That is the caller's problem, not the host's.

Both endpoints report only this host's view, matching /v0/tenant/onboard. Completed means this host's authorized mapping has already advanced past the base serial; InProgress means the change is still a proposal here.

New in add_hosts.rs

submit_add_hosts — the add-hosts counterpart to allocate_party. It re-reads head state, runs the validator, co-signs with an empty signed_by so the node picks its own key, and submits. Validation happens before this node's key touches the bytes, which is the whole point: the party already exists and already holds contracts, so a forged serial N+1 could evict its current hosts rather than merely create something unwanted.

Tests

Five unit tests: decode_all (including that one bad entry fails the whole batch, since a silently dropped entry would break the index alignment the signatures depend on), and wire-shape round-trips for both request DTOs — decman-wallet mirrors these types, so a renamed field would fail to deserialize on the other end.

The endpoint behavior itself needs a live Canton, so an integration-test phase is the honest coverage. That plus the wallet-side flow (§06 item 4) is the natural next PR.

cargo clippy --workspace --all-targets --all-features -- -D warnings is clean. Per the usual rule I have not run cargo test locally.

[Copilot]

Pull request overview

This PR wires the previously-added “add hosts to an existing external party” topology builder/validator into the Tenant API by adding prepare/onboard HTTP endpoints, associated request/response DTOs, and the workflow submission function that co-signs and submits the wallet-provided topology bundle.

Changes:

• Added POST /v0/tenant/add-hosts/prepare and POST /v0/tenant/add-hosts/onboard handlers and registered them in the server.
• Introduced wallet-facing DTOs for add-hosts prepare/onboard requests and responses (and re-exported them via server types).
• Added submit_add_hosts workflow function to validate, co-sign, and submit the wallet-signed add-hosts topology bundle.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/decman/src/workflow/external_party/add_hosts.rs	Adds submit_add_hosts for co-signing + submission of wallet-signed add-hosts topology.
crates/decman/src/server/types.rs	Re-exports new Tenant add-hosts DTOs for handler use.
crates/decman/src/server/mod.rs	Registers the new tenant add-hosts endpoints on the Actix server.
crates/decman/src/server/handlers/tenant.rs	Implements the new /v0/tenant/add-hosts/* endpoints plus shared base64 decode helper/tests.
crates/decman/src/server/handlers/mod.rs	Re-exports the new tenant add-hosts handlers.
crates/common/src/api.rs	Defines new API DTOs for add-hosts prepare/onboard request/response payloads.

Suppressed comments (1)

crates/decman/src/server/handlers/tenant.rs:443

• All submit_add_hosts(...) errors are mapped to HTTP 400, but submit_add_hosts can also fail due to internal RPC issues (signing/submission/topology reads) that should be 500 per the endpoint’s documented responses. This makes client retry/diagnostics harder.

        Err(e) => {
            tracing::error!("tenant add-hosts onboard: submission failed: {e:#}");
            return HttpResponse::BadRequest().json(ErrorResponse {
                error: format!("Failed to submit the add-hosts topology on this host: {e}"),
            });

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.