Freeze and unfreeze balances
Restrict or release a holder address or part of a holder balance for approved custodian cases.
Freeze and unfreeze controls let a custodian restrict a holder without changing token ownership. Use an address freeze when the holder address must be blocked as a whole. Use a partial freeze when only a specific amount needs to stay locked while the rest of the balance can still move. Use a partial unfreeze when the approved case allows some or all of the frozen amount to be released.
Custodian control, not a compliance rule
Freeze and unfreeze workflows require the Custodian role. They are administrative controls for approved legal, recovery, or compliance cases. They do not replace the asset's normal compliance policy, holder verification process, or custody approval procedure.
Choose the right control
Start with the narrowest restriction that matches the approved case.
| Case | Use | Result |
|---|---|---|
| The holder address must not transfer | Address freeze | Transfers involving the address are restricted until the address is released. |
| Only part of the holder's balance needs to stay locked | Partial freeze | The selected amount is frozen. The rest of the holder's available balance can still move if normal transfer checks pass. |
| A previously frozen amount can be released | Partial unfreeze | The selected amount is released from the holder's frozen balance. |
| The whole holder case is cleared | Address release plus any partial unfreeze still needed | The holder returns to the normal asset policy path after all restrictions are released. |
Use forced transfer only when the approved case requires moving tokens to another holder. See Forced transfer for that exception workflow.
Prerequisites
Before you start, make sure you have:
- the Custodian role for the asset
- the holder address affected by the case
- the amount to freeze or release when the case affects only part of a balance
- approval evidence for the hold, release, or correction
- the custody or operational approval required by your organisation
What each control changes
| Control | What DALP changes | What stays with the case record |
|---|---|---|
| Address freeze | Queues a custodian transaction that sets the holder address freeze flag for the token. Set freeze to true to freeze the address and false to release it. | DALP does not decide whether the whole-address hold is justified. The operator must match the freeze or release to the approved case. |
| Partial freeze | Queues a custodian transaction that freezes a positive token amount for the holder. DALP checks the indexed available balance before submitting the queued write when balance data is available. | DALP does not decide the legal hold amount. The operator must match the amount to the approved case. |
| Partial unfreeze | Queues a custodian transaction that releases a positive amount from the holder's frozen balance. | DALP does not decide whether the case is closed. The operator must keep the release approval with the case record. |
Address freezes, partial freezes, and partial unfreezes are queued write operations. Reconcile the queued transaction status and holder balances before submitting another instruction for the same case.
Freeze or unfreeze a holder balance
Open the right holder-control surface
For address freeze, partial freeze, and partial unfreeze operations, authenticate with an account that has the Custodian role for the asset. For an address freeze, use the DALP API or CLI. For an address release, use the DALP API with the same holder address and freeze set to false. For a partial freeze or partial unfreeze, go to Asset Management, select the asset, then choose Manage Asset and open the partial freeze or partial unfreeze control.
dalp tokens freeze-address --address 0xTOKEN --target 0xHOLDER
dalp tokens freeze-partial --address 0xTOKEN --target 0xHOLDER --amount 1000000000000000000
dalp tokens unfreeze-partial --address 0xTOKEN --target 0xHOLDER --amount 1000000000000000000Select the holder address
Choose the holder address affected by the approved case. If the holder is not visible, verify the address and asset before entering it manually.
Enter the freeze state or amount
For an address freeze, confirm whether the holder address should be frozen or released. For a partial freeze, enter a positive amount within the holder's available balance. For a partial unfreeze, enter a positive amount within the holder's currently frozen balance.
Review and authenticate
Review the holder address, amount, and asset symbol. Authenticate with the required operator factor and submit only when the values match the approved case.
Reconcile the result
Check the queued transaction status, holder balance, and frozen balance before submitting another partial freeze or unfreeze for the same case.
Production checks
Before using freeze and unfreeze controls in production:
- keep the Custodian role limited to approved operators
- define which cases allow an address freeze, address release, partial freeze, and partial release
- require evidence for every freeze and unfreeze decision
- reconcile queued write status and holder balances after submission
- keep retry behaviour tied to the same business instruction instead of creating duplicate holds
- periodically review open address freezes and frozen balances against the case ledger
Troubleshooting
| Issue | What to check |
|---|---|
| Control not visible | Verify that your operator account has the Custodian role for the asset and that the asset supports holder restrictions. Address freeze and release are available through the DALP API; address freeze is also available through the CLI. |
| Address freeze did not clear a partial hold | Address freezes and partial freezes are separate controls. Release the partial frozen amount when the case allows it. |
| Holder address should be released | Use the address-freeze control in release mode, then reconcile holder status before allowing normal transfers. |
| Freeze amount rejected | Check that the amount is positive and does not exceed the holder's available balance. |
| Unfreeze amount rejected | Check that the amount is positive and does not exceed the holder's frozen balance. |
| Holder still cannot transfer | Check address freeze state, remaining partial frozen amount, normal compliance checks, custody policy, and asset pause state. |
| Response lost after submit | Treat the instruction as pending until queued transaction status or holder balance proves the outcome. |
Related operations
For exception movements, see Forced transfer. For asset-level stop controls, see Pause and unpause an asset. For custodian permissions, see Per-Asset RBAC. For API use, see Token holders and transfers.