DALP transfer approval evidence review for regulated transfers

How the TransferApproval module gates regulated transfers with identity-bound approvals, expiry, consumption modes, and fee-feature exemptions.

TransferApproval requires an approval authority to grant permission before a regulated transfer executes. Each approval record names a sender identity, recipient identity, approved value, expiry window, and consumption mode. The compliance engine validates the record on every transfer attempt and consumes approval value only after the transfer succeeds. The indexed API gives you a review queue for the latest approval state, while the event log remains the lifecycle evidence source.

TransferApproval

TransferApproval requires pre-authorization before transfers. Each approval expires after a set duration. The approval mode controls consumption. The compliance engine can require an exact match, allow one transfer up to the cap, or permit multiple transfers until the approved total is spent.

Interface (capabilities)

Capability	Who can call	Inputs	On-chain effect	Emits	Notes
`setModuleParameters`	Token admin (via compliance)	Approval authorities, expiry, and the installed module's parameter schema	Stores approval config; expiry is a config-time duration applied to all approvals	None	Use approval-mode settings or exemption/one-time-use settings, not both
`approveTransfer`	Approval authority	Token, sender identity, recipient identity, value	Records approval for the sender, recipient, and approved amount with expiry timestamp	`TransferApproved`	Only addresses in `approvalAuthorities` can issue approvals
`revokeApproval`	Approval authority	Token, sender identity, recipient identity, value	Removes the active approval record	`TransferApprovalRevoked`	Any configured approval authority can revoke a pending approval
`canTransfer`	Compliance engine	Sender, recipient, amount	Checks the approval record and applies the configured approval mode	None	Validation only; consumption happens after a successful transfer
`transferred`	Compliance engine	Token, sender, recipient, amount	Marks consumed approval value after the transfer completes	`TransferApprovalConsumed`	Called by the engine after transfer execution

How pre-approval works

A compliance manager configures the approval authorities, the expiry duration, and the parameter model used by the installed module.
An approval authority issues an approval for a sender identity, recipient identity, and approved value.
The holder attempts a transfer between those identities.
The module checks that the approval is still active, not expired, and valid for the requested amount under the configured consumption rule.
After a successful transfer, the engine calls the transfer hook and the module records consumed approval value, emitting TransferApprovalConsumed where applicable.
If validation fails, the compliance engine blocks the transfer before consumption.

Approval lifecycle

Rendering diagram...

The event log records lifecycle decisions. The indexed approvals API holds the current approval state for the token and chain, so operators can review approvals by status (pending, consumed, or revoked) without replaying events on every check. Together, these records show whether an approval authority granted a transfer, whether the approval remained usable, and what happened when the holder attempted the transfer.

API and integration surface

Use the token transfer approval API when your external workflow needs to inspect, create, or cancel TransferApproval records for a token. The list endpoint is the review surface for indexed approvals, not a replacement for the event log.

Operation	Endpoint	Use it for
List approvals	`GET /api/v2/tokens/{tokenAddress}/transfer-approvals`	Reading indexed approvals, including `pending`, `consumed`, and `revoked` records
Create approval	`POST /api/v2/tokens/{tokenAddress}/transfer-approvals`	Recording a sender-to-recipient approval before the holder initiates the transfer
Revoke approval	`POST /api/v2/tokens/{tokenAddress}/transfer-approval-revocations`	Cancelling a pending approval that should no longer execute

The list endpoint reads indexed TransferApprovalComplianceModule events and returns paginated data, meta, and links fields. The indexed approval key includes the module address, token, sender identity, recipient identity, and approved value. API records expose that key as the composite id. Each row also carries the token, sender identity, recipient identity, and approver identity alongside the approved value and expiry, the current status, and creation and last-update timestamps.

By default, the collection sorts by newest approval first. Use filter[status] with pending, consumed, or revoked to narrow the list. Sort by createdAt, updatedAt, or value when an integration needs a stable review queue.

A pending record means the latest indexed lifecycle state for that approval tuple is a grant or re-grant. Earlier consume or revoke events can still exist for the same tuple. Check expiry before presenting the record as usable, and keep the transfer result with the review evidence when the holder used the approval.

An approval authority for the installed TransferApproval module must submit create and revoke operations. Both require fromWallet, toWallet, and a positive amount in base units. If the integration already knows both identity contract addresses from the approvals list, it may also send both fromIdentityAddress and toIdentityAddress. The platform rejects partial identity overrides. For request examples and operational retry guidance, see Token holders and transfers.

Approval modes

Use the approval mode to control how narrowly the compliance engine consumes approvals you issue.

Mode	Value	Consumption behavior	Typical use
Exact amount	`0`	One transfer must match the approved value exactly. After that transfer succeeds, the compliance engine marks the approval consumed and the holder cannot reuse it.	Strict regulated transfers where the approval record must match one settlement instruction.
Up to once	`1`	One transfer can use any amount up to the approved value. Transferring less than the approved value still consumes the approval.	Workflows where the final settled amount may be lower than the pre-approved cap.
Up to total	`2`	Multiple transfers can spend against the approval until the approved total is spent. Further transfers require a new approval or a higher amount.	Programmatic or staged settlement where one approval covers several partial transfers.

Approval modes do not remove the expiry check during normal transfer validation. Once the configured approval window has passed, validation rejects the approval even if unused value remains. When the platform operates in accounting-only scope, it skips validation but still runs post-transfer accounting hooks.

Rewriting-feature compatibility

TransferApproval is the one compliance module that needs extra setup when you use it on an asset that also has a rewriting feature, such as the Transaction Fee feature. Every other compliance module is compatible with rewriting features without changes.

A rewriting feature splits one transfer into legs. A transfer of value V with a fee becomes a recipient leg for the net amount plus a fee leg to the fee collector. The compliance engine checks each leg independently. The fee collector is a destination the approval authority never pre-approved, so without further configuration the compliance engine rejects the fee leg and the whole transfer reverts.

The External Transaction Fee feature works differently and does not rewrite the asset transfer into legs. The feature adds a separate fee-token transfer from the payer to the fee recipient on top of the asset operation, so the asset transfer keeps its original recipient and amount. Because the feature creates no extra asset leg, TransferApproval sees only the original transfer, and the External Transaction Fee feature needs no exemption.

Plan for this interaction when you configure TransferApproval alongside a fee feature:

Approval mode	Behavior with a rewriting feature
Up to once	Compatible. The recipient leg delivers the net amount, which is within the approved cap, so the recipient leg passes.
Up to total	Compatible. The recipient leg spends the net amount against the approved total, leaving the remainder for later transfers.
Exact amount	Incompatible by design. The net amount delivered after the fee never equals the approved value, so the recipient leg cannot match an exact approval.

To clear the fee leg, an approval authority exempts the fee collector for the token. The exemption waives only the TransferApproval check for transfers to that collector. Identity registration and every other compliance module still apply to the fee leg, so the exemption never opens a compliance-free path.

The platform enforces an exemption only while the authority that set it remains an approval authority. Removing that authority stops the platform from enforcing the exemption, but does not clear the stored record. If the same authority is later added back, the platform enforces its earlier exemptions again. When you rotate authorities, explicitly clear any exemptions that should no longer apply rather than relying on authority removal to retire them.

For the order in which fee features and compliance run on a transfer, see Token features overview.

Configuration

Choose the parameter schema that matches the installed module. Use approval-mode settings or exemption/one-time-use settings in your payload, but not both.

For the approval-mode model, configure:

Option	Description
`approvalAuthorities`	Addresses authorized to issue or revoke approvals
`approvalMode`	Consumption rule for approvals: exact amount, up to once, or cumulative up to total
`approvalExpiry`	Duration in seconds, from 1 to 31,536,000 seconds; set at configuration time and applies to all approvals

For the exemption model, configure:

Option	Description
`approvalAuthorities`	Addresses authorized to issue or revoke approvals
`oneTimeUse`	If true, a matching approval is consumed after one successful transfer
`approvalExpiry`	Duration in seconds, from 1 to 31,536,000 seconds; set at configuration time and applies to all approvals
`allowExemptions`	If true, recipients matching the exemption expression bypass the approval requirement
`exemptionExpression`	RPN expression identifying exempt investors

Validation ignores extra keys that do not belong to the installed module's schema, so keep configuration payloads schema-specific and do not mix exemption settings with approval modes.

After configuration, the approval mode is fixed for that module instance. Deploy a new TransferApproval module to change the mode.

Operating patterns

Pattern	Approval mode	Why it fits
Exact settlement ticket	Exact amount	The approval record must match one transfer instruction.
Capped single transfer	Up to once	The final transfer may settle below the approved cap, but only once.
Staged partial settlement	Up to total	Several partial transfers may spend down one approved total before expiry.

Key invariants

Each approval covers one specific sender identity, recipient identity, and approved value, plus an expiry and an approval mode. The platform does not treat an approval as a blanket permission for any transfer.
An investor with multiple wallets shares the same identity, so one approval covers all wallets tied to that identity.
approvalExpiry is a config-time duration. All approvals share the same expiry window; the platform does not support per-approval expiry overrides.
Exact amount mode is the strictest pattern. Use up-to modes only when your operating process allows partial consumption.
approvalMode is fixed after configuration. Redeploy the module to change the mode.
The compliance engine rejects expired approvals during normal transfer validation; the approval authority must reissue. Accounting-only scoped modules can still run post-transfer accounting hooks even when the engine skipped validation.

Operational signals

TransferApproved: emitted when an approval authority grants a transfer approval
TransferApprovalConsumed: emitted when the compliance engine fully consumes an approval. Exact amount and up-to-once approvals emit after the successful transfer. Up-to-total approvals emit only when the remaining approved amount reaches zero, not on every partial transfer.
TransferApprovalRevoked: emitted when an approval authority revokes an approval
Monitor for ComplianceCheckFailed revert errors in failed transactions when transfers lack valid approvals

Evidence and review records

Use the on-chain event log as the audit trail for approval lifecycle decisions. The indexed approvals API is your review surface for the latest approval records on the configured chain and token. The indexer stores each approval by module address, token, sender identity, recipient identity, and approved value. The API reports the current status as pending, consumed, or revoked so you can check the state at any point.

For an evidence pack, pair the approval list with the lifecycle transactions that matter to your workflow. Keep the approval grant record, the transfer consumption record, the revocation record, and failed-transfer records together so a reviewer can see both the requested approval and the final transfer outcome.

Review question	Primary record	Check before relying on it
Was a transfer approved for these identities and this value?	`TransferApproved` event and approvals API row	Sender identity, recipient identity, token, module address, value, and expiry
Is the approval still open for use?	Approvals API row with `status: pending`	Expiry, transfer history, and remaining value for up-to-total approvals
Was the approval used?	Successful transfer transaction and `TransferApprovalConsumed` event where emitted	Approval mode, consumed value, and final transfer status
Was the approval cancelled?	`TransferApprovalRevoked` event and approvals API row with `status: revoked`	Revoking authority and timestamp
Why did a transfer fail?	Failed transaction with `ComplianceCheckFailed`	Whether the approval was missing, expired, revoked, already consumed, or too small for the requested amount

Failure modes & edge cases

Any configured approval authority can revoke a pending approval. The compliance engine does not consume revoked approvals.
The compliance engine rejects a reuse of an exact amount or up-to-once approval after a successful transfer, because the approval has already been consumed.
The compliance engine rejects spending more than the remaining value of an up-to-total approval during normal validation. In accounting-only scope, the engine skips validation and the post-transfer hook clamps the remaining approval value to zero for accounting.

Transfer approval