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

# Canopy Admin Permissions and Protocol Emergency Controls

The owner can never compromise collateral safety or block redemptions. Admin control is scoped to fee configuration and a limited entry pause.

## Ownership Model

The OTCVenue inherits OpenZeppelin's `Ownable2Step`, which requires a two-step ownership transfer: the current owner nominates a new owner, and the new owner must accept. This prevents accidental ownership transfers to incorrect addresses.

## What the Owner Can Do

The following actions are available to the designated owner address:

* **Set protocol fee rate** — Configure the percentage fee applied to new offers, expressed in basis points (bps). The fee rate is hard-capped at `MAX_FEE_BPS = 100` (1.00%). The owner cannot set a fee above this cap.
* **Update fee recipient address** — Change the address that receives collected fill fees on future offers. This does **not** affect existing offers — each offer snapshots the fee recipient at creation time.
* **Pause new offer creation and fills** — Activate the entry pause, which prevents new offers from being submitted **and** new fills from being executed. See [Emergency Pause](#emergency-pause) for details.

<Note>
  Fee changes and fee recipient changes only affect **future** offers. Each offer snapshots `feeBps` and `feeRecipient` at creation time, so existing offers continue to use the rate and recipient that were active when they were created.
</Note>

## What the Owner Cannot Do

The following actions are **outside the owner's authority**, by design:

* ❌ Seize, redirect, or withdraw escrowed collateral belonging to any offer
* ❌ Cancel offers on behalf of their sellers
* ❌ Block or delay redemptions after a series reaches its unlock time
* ❌ Modify the terms of any existing offer (price, size, expiry, unlock time, or buyer restrictions)
* ❌ Mint or burn claim tokens outside of the normal fill and redemption flows
* ❌ Change the fee rate or recipient on an offer that already exists
* ❌ Pause cancellations or redemptions

These restrictions are enforced at the contract level — they are not policy commitments that depend on owner behavior. A compromised owner key cannot perform any of the above actions.

## Fee Handling

Protocol fees are collected at fill time from the buyer's quote tokens, paid **on top of** the seller's proceeds. The fee is computed on the base quote cost and transferred separately to the fee recipient.

**Fee formula:**

```
fee = mulDiv(quoteCost, feeBps, 10_000)
```

The buyer's total outlay is `quoteCost + fee` (plus any transfer taxes). The seller receives `quoteCost` (minus any transfer tax on the quote token, if applicable).

**Numeric example:**

> On a **10,000 USDC base quote cost** with a protocol fee rate of **20 bps**:
>
> ```
> fee            = mulDiv(10,000, 20, 10,000) = 20 USDC  →  fee recipient
> sellerProceeds = 10,000 USDC                            →  seller
> buyerTotal     = 10,020 USDC                            →  total debited from buyer
> ```
>
> The seller receives 10,000 USDC, the fee recipient receives 20 USDC, and the buyer pays a total of 10,020 USDC.

<Info>
  Fee rates are expressed in basis points where 1 bps = 0.01%. A rate of `20` means 0.20%, `50` means 0.50%, and `100` (the maximum) means 1.00%.
</Info>

## Emergency Pause

If a critical vulnerability is discovered in the protocol, the owner can activate an entry pause that prevents new offers from being created **and** new fills from being executed. This gives protocol maintainers and security researchers time to assess the issue without allowing new capital to enter or interact with the affected code paths.

The pause is controlled by the `whenEntryOpen` modifier, which guards both `createOffer` and `_fill` (the internal function behind both `fill` and `fillWithLimits`).

The pause is **narrowly scoped**:

<Note>
  Even with the entry pause active, sellers can still cancel their own offers to recover unfilled collateral, and claim holders can still redeem against unlocked series. The `cancel` and `redeem`/`redeemWithMinimum` functions are deliberately **not** gated by the entry pause.
</Note>

| Function                       | Affected by Pause?          |
| ------------------------------ | --------------------------- |
| `createOffer`                  | ✅ Yes — blocked when paused |
| `fill` / `fillWithLimits`      | ✅ Yes — blocked when paused |
| `cancel`                       | ❌ No — always available     |
| `redeem` / `redeemWithMinimum` | ❌ No — always available     |

## Deployment Trust Considerations

The security properties described above assume the owner address itself is appropriately secured. A single externally owned account (EOA) as the owner key is a significant operational risk — a compromised key could immediately change fee rates, activate a pause (blocking fills), or initiate an ownership transfer without any delay.

<Warning>
  Before trusting a Canopy deployment, verify that the owner address is a multisig wallet (such as a Gnosis Safe) or a timelocked contract with a meaningful delay. An EOA owner key means a single point of compromise for all protocol-level parameters. Check the owner address on-chain and confirm the governance setup with the deploying team before depositing significant assets.
</Warning>