With the own-gateway compliance rule, a custody receipt moves only between a client and that client's own gateway, which burns it when it pays coins out.
A custody receipt is the token a client holds while its coins sit in custody. It is an ordinary DALP asset with the same decimals as the coin, and one receipt asset exists for each coin the organisation enables.
Gateways mint it only against coins they have received. The receipt's supply management role can also mint, so the organisation leaves that role unassigned.
A compliance rule on the receipt keeps it in a closed loop between a client and that client's own gateway, and the add-on refuses to enable a coin whose receipt lacks that rule.
What a custody receipt is
A custody receipt is the asset a client holds while its coins sit in custody. It is an ordinary DALP asset, so the same compliance, identity, freeze and forced transfer controls apply to it as to any other, and it shows in the client's wallet like any other holding. The custody receipt for a coin has the same number of decimals as the coin, so one receipt unit stands for one coin unit before any fee owed.
The custody gateway add-on is the organisation's one-time deployment of the gateway contracts. It enables a coin by binding it to its custody receipt. After that, the custody gateway mints and burns receipts of that coin. A client who wants coins back returns receipts to the gateway instead of selling them on.
How the receipt is backed
The gateway backs each receipt by doing its steps in a fixed order. On a deposit, the gateway checks that the coins are present and not already counted, and only then mints receipts to the client's wallet, less the deposit fee when the gateway deducts it. On a withdrawal, the gateway burns the receipts in the same transaction that pays the coins. Through the gateway, the client never loses a receipt without getting the coins, and the gateway mints no receipt for coins it did not receive. Two roles on the receipt act outside that guarantee: a forced transfer by the custodian role, and a mint or burn by the supply management role.
The receipt has a supply delegate feature, a list of the accounts allowed to mint and burn it. The list holds the add-on's factory, the contract that creates the gateways. The factory confirms that a caller is one of its own gateways. The receipt therefore needs one entry, and every gateway of the organisation can mint and burn in its name. A gateway of another organisation cannot.
The receipt still has the ordinary supply management role, and an account that holds it can mint and burn without the gateway. Keep that role unassigned on a custody receipt, because a receipt minted that way has no coins behind it.
The add-on refuses to enable a coin whose receipt carries a transaction fee, fee accounting or assets-under-management fee feature. Fees on deposits and withdrawals live in the gateway, where they are set per coin and stored with each request. In the default mode the gateway deducts a deposit fee before it mints and a withdrawal fee before it pays. In accounting-only mode it mints and pays the full amount and records the fee as owed, so the amounts on this page exclude any fee owed.
When a custodian must accept a forwarded deposit before the receipts are usable, the gateway places a hold on the minted receipts in the client's wallet. The receipt is then visible but cannot be spent until the custodian accepts the coins or the deposit is returned.
Where the receipt may move
A receipt can move in three ways. A client returns it to its own gateway to request a withdrawal, and the receipt waits locked in the gateway's escrow. The gateway sends it to the client, when a deposit mints it or when a request ends and the receipts return. The gateway burns it when it pays coins out.
A compliance rule that limits transfers to the client's own gateway keeps a receipt in a closed loop between a client and that gateway. The add-on refuses to enable a coin whose receipt lacks the rule, and it checks only at enablement. A holder of the receipt's governance role can still remove the rule later, or point the receipt at another compliance contract, and the add-on does not check again. Without it, the receipt's other compliance rules decide who may receive it, and a client may be able to send it to another eligible wallet. Those rules also keep applying to transfers into the gateway.
With the rule in place, a client cannot pass a receipt to another person or park it at another client's gateway, because the receipt would stop standing for coins that the client's own gateway holds. A forced transfer by the receipt's custodian role skips this rule and can move receipts to any wallet with a verified identity in the receipt's identity registry.
The same rule applies to minting. The gateway mints only to a wallet of its own client, and a deposit whose receiving wallet is not a wallet of that client rests as mint refused until the gateway managers decide.
A frozen client wallet cannot receive a mint, as on any other asset. Custody gateway defines each deposit stage. Where the deposit goes depends on the screening mode and the path. With the default always-quarantine mode, the deposit rests in quarantine and clearing it fails while the wallet is frozen. A reported transfer that reaches the mint rests as mint refused. A direct deposit with screening off fails and leaves no record. Receipts returning from a cancelled request wait as return pending until the wallet is unfrozen.
What counts as backing
Each receipt is backed through its own gateway's records, and the gateway never counts quarantined coins, unsupported transfers or unallocated coins as backing for a payout. The optional collateral compliance rule on the custody receipt can add a further check on supply.
Frequently asked questions
Does holding a custody receipt cost a fee?
No. The add-on refuses to enable a coin whose receipt carries a fee feature, so holding or moving it charges nothing unless such a feature is added later. Deposit and withdrawal fees are set in the gateway and apply when coins enter or leave.
Does the receipt have a different number of decimals than the coin?
No. The add-on checks that the receipt and the coin have the same decimals when it enables the coin, so the receipt amount equals the coin amount without conversion.
Who can mint a custody receipt?
A gateway created by the organisation's custody gateway add-on, and any account the organisation grants the supply management role. Leave that role unassigned so that gateways are the only minters, as How the receipt is backed explains.