# Custodian watch

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custodian-watch
How a custodian learns of privileged actions on tokens it holds, and why a factory upgrade of those tokens waits for the custodian's notice.

A custodian holds tokens that another organisation issued and administers. The issuer's wallets can freeze, force-transfer, mint, burn, pause, recover and change the roles on those tokens, and the issuer can upgrade the token factory that deployed them. The custodian watch tells a custodian when that happens, and holds a factory upgrade back until the custodian has had notice.

## What the watch covers [#what-the-watch-covers]

An organisation subscribes to the watch. The watch then covers each token the organisation custodies: a token that one of its watched custody addresses held at the start of the watch window or received during it. The window is the one the custody watch list already keeps for each address.

The watch looks at these actions, each on chain:

| Action | What it does |
| --- | --- |
| Forced transfer | Moves tokens out of a holder's wallet |
| Recovery | Moves a lost wallet's balance to its replacement |
| Freeze and unfreeze | Locks or releases an address or part of a balance |
| Mint and burn | Changes the supply |
| Pause and unpause | Halts or resumes transfers of the token |
| Role grant and revoke | Changes who may use the actions above |
| Implementation upgrade | Replaces the code the token runs, recorded once by the factory |

An action counts only when its on-chain sender is outside the custodian's organisation. The organisation's own wallets are the wallets of its participants, the controller of a participant's smart wallet, and its custody watch addresses. A freeze that the custodian signs itself raises nothing.

## What a custodian receives [#what-a-custodian-receives]

Each action raises one operations case for the custodian, of the kind **Privileged action on a custodied token**. The case names the action, the token, the sender outside the organisation, the affected wallet and amount where the action has them, and the transaction. A forced transfer, a recovery, a burn and an implementation upgrade open as critical. The other actions open as warnings.

The case reaches the custodian in two places. The organisation's webhook endpoints receive `operations.case.opened`, as [the event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#operations) describes, and the case appears in the **Cases** tab of Custody under Business operations. The platform raises a case once for each log entry on chain, so a retry never repeats it.

The watch starts at the head of the chain when an organisation subscribes. It reports what happens from that point and does not report earlier history. The platform checks for new actions every 15 seconds. If a check fails, the next one picks up from the same place.

## Notice before an upgrade [#notice-before-an-upgrade]

An upgrade of a token factory changes every token the factory deployed. When custodians hold tokens of a factory, the system upgrade refuses to touch that factory until an upgrade was scheduled for it and its notice has ended.

- **Subscribe with a notice period.** Each custodian sets the business days of notice it asks for, from 0 to 60. The default is 5. The days count Monday to Friday in UTC and keep the time of day. Public holidays are not modelled.
- **Schedule the upgrade.** The system's organisation records the factory to upgrade. Every subscribed custodian holding tokens of that factory receives a case of the kind "Upgrade scheduled for custodied tokens" at once. The upgrade may first run when the longest notice among those custodians ends.
- **Run the upgrade.** System updates upgrades the factory only after that time. Before it, the run stops and states when the upgrade may run. When no custodian holds tokens of the factory, the upgrade needs no schedule.
- **Cancel.** The organisation can cancel an upgrade that has not run. The record stays as cancelled and the custodians' cases are resolved.

A custodian that raises its notice period after an upgrade was scheduled can lengthen the wait: the run checks the notice again when it starts.

### Emergency upgrades [#emergency-upgrades]

An emergency upgrade bypasses the notice. It needs a reason, it may run at once, and it still notifies every custodian at once, with a critical case. Use it for an upgrade that cannot wait, such as a fix for an exposed key.

## Who can do what [#who-can-do-what]

The organisation owner or a platform administrator subscribes, changes the notice period, unsubscribes, schedules an upgrade and cancels one. Each of these writes is a system administration change, so an organisation whose approval policy holds that class sends it for a second person's approval first. Reading the subscription or the list of scheduled upgrades needs a reporting role on the system.

The routes are in the Platform API under `reporting.custodianWatch`: `PUT /api/v2/reporting/custodian-watch` to subscribe, `POST /api/v2/reporting/custodian-watch/scheduled-upgrades` to schedule an upgrade, and the matching reads and deletes. The [API reference](https://docs.settlemint.com/docs/api-reference) lists each with its schema.