feat: validate transfer recipient party

[sadiq1971]

Problem

Transfers to a raw to_party_id were only syntax-checked. Two failure modes surfaced as 500s at Canton submission:

• PROMPT/DEMO are internal tokens not hosted on external nodes, but a transfer to an external party id was still submitted and failed on-ledger.
• USDCx (the supported external-transfer demo token) to a well-formed but nonexistent party id also failed only at submission.

Changes

Recipient validation (pkg/transfer) — both Prepare (raw party-id form) and SendCustodial now run checkRecipientParty after syntax/self checks:

• Recipient found in the user DB → registered user, any supported token.
• Not in DB + internal-only token → 400 recipient party is not registered with this service and <TOKEN> does not support transfers to external parties.
• Not in DB + external token → the party must exist in the participant topology, else 400 recipient party id is not known on the network. Topology lookup failure → 502.

Token config — new external_transfer flag on supported_tokens entries marks tokens transferable to unregistered/external parties. Set for USDCx in the deploy configs; PROMPT/DEMO default to internal-only.

Topology check (pkg/cantonsdk/identity) — new PartyExists on the identity client using PartyManagementService.GetParties (unknown parties are omitted from the response rather than erroring).

Error mapping safety net — Canton rejections from PrepareTransfer/TransferByPartyID now map InvalidArgument/NotFound/FailedPrecondition → 400 and Unavailable/DeadlineExceeded → 502 via mapTransferErr, so races that slip past the pre-checks no longer 500.

Tests

• Internal token → unregistered party rejected (prepare + custodial)
• USDCx → topology-known external party succeeds (prepare + custodial)
• USDCx → unknown party → 400; topology lookup outage → 502
• Ledger NOT_FOUND on submission → 400, not 500
• Existing DEMO→party-id tests updated to stub a registered recipient

[gemini-code-assist]

Code Review

This pull request introduces support for transferring tokens to external participant nodes (external transfers, e.g., USDCx) by adding an external_transfer configuration option and implementing a PartyExists check in the Canton identity client. The TransferService has been updated to validate recipient party IDs, ensuring unregistered parties are only allowed for external-transfer tokens and exist within the network topology. The review feedback highlights critical improvements to prevent potential nil pointer dereferences in PartyExists and TransferService, and suggests using errors.As in mapTransferErr to robustly extract gRPC status codes from wrapped errors.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 32 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@83d4116). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
pkg/transfer/service.go	64.00%	16 Missing and 2 partials ⚠️
pkg/cantonsdk/identity/client.go	0.00%	13 Missing ⚠️
pkg/app/api/server.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #362   +/-   ##
=======================================
  Coverage        ?   33.81%           
=======================================
  Files           ?      163           
  Lines           ?    12585           
  Branches        ?        0           
=======================================
  Hits            ?     4255           
  Misses          ?     7989           
  Partials        ?      341           

Flag	Coverage Δ
unittests	33.81% <50.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/token/config.go	83.33% <ø> (ø)
pkg/app/api/server.go	0.00% <0.00%> (ø)
pkg/cantonsdk/identity/client.go	0.00% <0.00%> (ø)
pkg/transfer/service.go	73.29% <64.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dhyaniarun1993]

Base branch seems incorrect