Custody adapter mapping
Luvion keeps policy, approvals, authorization, and evidence independent from a specific wallet or custody provider. A named integration translates one provider API into the tested adapter contract while preserving the same authorization core.
A named provider integration becomes ready when this mapping is completed, implemented, tested against its sandbox, and jointly accepted.
Required logical operation
create_or_reconcile(exact_request) -> completed | rejected | retryable
The lowercase hexadecimal Luvion request_id is the provider idempotency key.
Every retry first checks whether the provider already created an operation for
that key. If it did, the adapter returns that operation instead of creating a
second transfer.
Partner mapping worksheet
| Decision | Partner answer required |
|---|---|
| Sandbox and production endpoints | Base URLs, region, network restrictions |
| Authentication | API key, request signature, OAuth, mTLS, or other mechanism |
| Treasury account | Luvion tenant/account ID to provider vault or wallet ID |
| Networks | Canonical network IDs to provider network codes |
| Assets | Contract address or asset ID, decimals, and provider symbol |
| Destinations | Allowlist source, update process, and enforcement location |
| Idempotency | Native key support or exact reconciliation query |
| Status lifecycle | Pending, accepted, broadcast, confirmed, failed, cancelled |
| Completion meaning | provider_accepted, broadcast, or confirmed |
| Error classes | Durable rejection versus retryable provider or transport error |
| Webhooks and polling | Signature verification, fallback polling, and timeout |
| Evidence | Operation ID, transaction hash, timestamps, and retention period |
Request and response binding
The adapter receives the exact tenant, request, network, account, asset, amount, destination, payload hash, policy context, approval context, and authorization-certificate metadata. Its response repeats the contract version, adapter ID, idempotency key, and canonical request digest.
Luvion rejects a response before persistence if any binding differs. API keys, provider signing secrets, and raw credentials never belong in this payload or in the evidence export.
Outcome classification
| Outcome | Use when | Luvion behavior |
|---|---|---|
completed | The agreed completion condition was reached | Persist one receipt and mark executed |
rejected | The provider made a durable policy or business rejection | Do not create a receipt; do not retry as a transport failure |
retryable | Timeout, rate limit, pending reconciliation, or temporary provider failure | Retry later with the same idempotency key |
Release gates
Before a named adapter enters a design-partner validation:
- the partner signs off the completed mapping worksheet;
- the adapter proves duplicate prevention across a crash and retry;
- altered request or response bindings fail closed;
- provider errors are covered by deterministic classification tests;
- secrets are redacted from logs and evidence;
- timeout, retry, and reconciliation behavior is reproduced in sandbox; and
- the selected completion meaning is visible in the final evidence package.
Production additionally requires reviewed transport authentication, TLS, credential rotation, monitoring, rate limits, incident ownership, and a provider-specific operational runbook.