> ## Documentation Index
> Fetch the complete documentation index at: https://musubinetwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorization Workflow

> Multi-party DvP co-signing, quote review, and how this differs from standard multisig.

As a sender custodian, you're a co-signer in a multi-party FX settlement — not just a send/receive operator. No assets move without your cryptographic co-signature.

## Dual Authorization: Institution + Custodian

Every trade requires two independent authorizations from the sending side:

| Step                  | Who                       | What They Do                                             |
| --------------------- | ------------------------- | -------------------------------------------------------- |
| 1. Select quote       | Institution (your client) | Reviews competing quotes, picks the best rate            |
| 2. Authorize movement | You (the custodian)       | Co-signs the quote acceptance, authorizing asset release |

Neither party can act alone. The institution cannot move assets without your co-signature. You cannot initiate a trade — only authorize one that your client has requested.

## How This Differs from Standard Multisig

If you're used to threshold multisig (2-of-3, 3-of-5), the Canton model works differently:

|                | Standard Multisig (EVM)                  | Canton 4-Party Approval                                           |
| -------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| **Signers**    | Anonymous key holders (any 2 of 3)       | 4 named parties with specific roles                               |
| **Threshold**  | N-of-M (any combination)                 | All 4 required — no substitutes                                   |
| **Ordering**   | Signatures collected simultaneously      | Rolling approval — each party signs sequentially                  |
| **Mechanism**  | On-chain signature aggregation           | DAML choice exercise — each `Approve` creates an updated contract |
| **Visibility** | All signers see the same on-chain data   | Each party sees only what they're authorized to see               |
| **Veto**       | Any signer can refuse (blocks threshold) | Any of the 4 parties can refuse (blocks settlement)               |

The four required confirming parties for every settlement (Canton mediator confirmation derived from per-leg `Allocation` contracts' signatory closure — see ADR-0004 §B4):

```mermaid actions=false theme={null}
graph TD
  A[Network Operator<br/>coordinates 4-party settlement] --> S[Settlement]
  B[Sender Custodian<br/>authorizes asset release] --> S
  C[Market Maker<br/>commits target currency] --> S
  D[Receiver Custodian<br/>confirms receipt capability] --> S
```

## Why You See Quotes

Competing quotes are visible to you because your co-signature is the best-execution gate. Three practical consequences:

* Your co-signature confirms the rate is acceptable at the moment of authorization.
* You can refuse a quote whose rate doesn't meet the cost guard or looks off-market — the acceptance fails and no assets move.
* `quote_accepted_at` becomes the timestamped evidence of which rate you authorized.

## The Authorization Flow

<Steps>
  <Step title="Order Proposal Arrives">
    Your client creates an FX order referencing you as their custodian. The order appears on your system with:

    * Target currency and amount (e.g., 100,000 USDCx)
    * Target currency (USDCx)
    * Receiver institution and their custodian
    * Optional cost guard (`source_amount_max`)

    You can **accept** the proposal (order proceeds to quoting) or **reject** it (order is cancelled).
  </Step>

  <Step title="Market Maker Quotes Arrive">
    After you accept the proposal, market makers submit competing quotes. You see all quotes for orders you custody:

    | Quote | FX Rate | USDCx Offered | Valid Until |
    | ----- | ------- | ------------- | ----------- |
    | MM-A  | 112.0   | 11,200,000    | 30s         |
    | MM-B  | 8.8950  | 88,950,000    | 30s         |
    | MM-C  | 8.9200  | 89,200,000    | 20s         |

    You and your client review these independently. The institution selects the best one; you co-sign.
  </Step>

  <Step title="You Co-Sign the Quote Acceptance">
    When the institution selects a quote, the acceptance requires your co-signature:

    * **Your co-signature authorizes** the JPYSC0 release from your custody
    * **Without your co-signature**, the quote acceptance fails and no assets move
    * Musubi validates: quote still valid (`valid_until` not passed), cost guard met, order still PENDING

    After your co-signature, the order transitions to **QUOTED** and settlement proceeds automatically.
  </Step>

  <Step title="4-Party Settlement Approval">
    Your approval from the previous step carries forward into the rolling approval process. The settlement protocol collects the remaining approvals (market maker, receiver custodian) automatically. Once all four have signed, the atomic DvP executes.
  </Step>

  <Step title="Settlement Confirmation">
    The atomic DvP completes in \~4 seconds. You see the settled order with:

    * `transaction_hash` — single proof covering all four legs
    * `settled_at` — settlement timestamp
    * Final amounts and executed rate

    Your client's JPYSC0 balance decreases; the receiver custodian's USDCx balance increases. Both changes are atomic.
  </Step>
</Steps>

## Receiver Custodian Workflow

As a receiver custodian, your workflow is simpler:

1. **Settlement confirmation arrives** — USDCx deposited in your custody by the atomic DvP
2. **Update client balance** — credit the receiver institution's account
3. **Reconcile** — match `transaction_hash`, amounts, and timestamps against your records

No approval is required from you during the trade flow. Your authorization is established up front through your withdrawal-address whitelist configuration.

## What You Can Block

As a sender custodian, you have veto power at two points:

| Action                                 | Effect                                                                                       |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Reject order proposal**              | Order is cancelled immediately. No quotes are solicited.                                     |
| **Refuse to co-sign quote acceptance** | Quote acceptance fails. Order remains PENDING until another quote is accepted or it expires. |

If something looks wrong — unusual amount, unfamiliar receiver, suspicious timing — you can stop the trade.

### Declining a quote

When you click **Decline** on a pending co-sign:

1. You must enter a `rejection_detail` of at least 20 characters. This text becomes a permanent audit field — auditors will read it.
2. The proposed quote is **terminally rejected** (β quote-tainting) — the same quote cannot be re-proposed by the institution. The market maker sees their `FXQuote` transition to `QUOTE_REJECTED` immediately on their feed.
3. Other PENDING quotes for the same order remain selectable. The institution may propose a different one.
4. The FX order stays in `PENDING` status until a different quote is co-signed or the order's `expiresAt` is reached.

The institution can also withdraw its own proposal before you act, by calling `POST /api/v1/orders/{intent_id}/quotes/{quote_id}/withdraw-acceptance` with a 20-character `withdrawal_reason`. After withdrawal, the proposed quote stays PENDING and the institution can pick another.

If neither side acts before `quote.validUntil`, the operator's expiry cron archives the proposal automatically — no on-ledger trace beyond the `QuoteCoSignExpired` SSE event.