Skip to main content

Transfer-Path Compliance

Transfer-Path Compliance enforces a regulated token's rules inside the on-chain transfer, so an ordinary movement that fails a rule reverts before it settles.
Both failures land in the same place: nothing moved.A transfer or mint request reaches the token. The token first checks whether the recipient passes the identity registry checks. If not, the transaction reverts. If that passes, the token evaluates every configured rule, and any single failure also reverts. Both failures end in the same state: no balances change. A generic rejection may require simulation to identify the blocker. Only when the identity check and every rule pass do balances update and rule state record the movement. Nothing partially settles: the movement happens whole, or it does not happen.Both failures land in the same place: nothing moved.The same figure as the desktop variant, drawn portrait for phone widths: the request runs through two gates, identity then rules, and a failure at either gate turns right into the same reverted state while a pass at both gates continues down to balances update.

Ordinary transfers must pass identity and compliance checks, and a failed check reverts the transaction and its balance changes.

  • Ordinary transfers and mints run the asset's applicable checks before balances change, and a failing rule reverts the movement. Every token bound to the organisation's system compliance engine on its network inherits global controls alongside its own modules: a token factory binds each token it deploys, and a factory migration binds older tokens. Forced transfers, wallet recovery and bypassed recipients skip some checks, and the Governance and System manager roles can change the checks themselves. Controls and evidence lists each.

  • Eligibility depends on on-chain claims and configured rules. An off-chain decision affects transfers after the corresponding claim or policy update reaches the chain.

  • A read-only pre-check reports current blockers before signing. A clear result does not reserve eligibility or guarantee later execution.

Why transfer-path compliance matters

For an institution issuing regulated assets, transfer-path compliance means the rules you configure travel with the asset: who may hold it, in which jurisdiction, up to what cap, under what lock-up. The token enforces applicable rules inside ordinary transfers and mints, including calls made outside the Platform API.

Transfer-path compliance runs on every ordinary transfer and mint across the whole asset lifecycle. The same eligibility registry that decides who may receive the first minted unit checks every later transfer.

On-chain checks enforce the recorded policy. They do not establish that the policy is legally sufficient or that off-chain evidence is current.

Your existing compliance providers keep their role. An accredited know-your-customer (KYC) or anti-money-laundering (AML) provider becomes an on-chain issuer: its passed check grants a holder eligibility, and its sanctions hit revokes it. The platform enforces the rules you configure. The legal policy, the provider relationships, and the decision to change a rule stay with your organisation.

Running compliance day to day

Choose the rules each asset enforces and keep holder eligibility current. A country allow list, investor-count cap, or minimum holding can each block a transfer for a different reason. The platform applies whatever configuration exists when value moves, so rule changes and identity updates take effect on the next transfer.

You configure rules per asset under its Governance role, either picking modules one at a time or applying a policy template, a named, versioned package of preconfigured modules you reuse across issuances. The Governance role can change or turn off those modules at any time after issuance. Reach for a template once you repeat the same rule set. A one-off asset with a bespoke mix costs less to hand-pick than to version. A Compliance manager installs a rule that must hold everywhere, such as a sanctions block list, once as a global control. Every bound token inherits it at once, and that token's compliance view marks it as inherited. A new global control governs future movements only, never balances that already settled.

Eligibility work is claims work: you review a participant's evidence off-chain, or a connected provider sends its verdict, and a trusted issuer records the result as a claim on the participant's on-chain identity. Revoking the claim withdraws eligibility the same way.

Two feeds govern ordinary movements.The eligibility feed carries off-chain review to a trusted issuer, who issues or revokes a claim on the holder's identity. The rule feed carries the asset's policy, a template or hand-picked rules, into the rules configured on the asset. Both feeds converge at the next transfer or mint attempt: when in-scope rules pass the movement executes, and when a rule fails the movement is blocked and simulation can help identify the blocker.Two feeds govern ordinary movements.The same figure as the desktop variant, stacked for phone widths: the eligibility feed and the rule feed each resolve to a state, both feed the next transfer or mint attempt, and that attempt either executes or reverts.

An ordinary movement passes only when both the rules configured on the asset and the claims on each holder's identity agree.

When a transfer keeps failing, the token's “Transfer pre-check” tab explains why: enter the sender, recipient and amount, and it runs that exact transfer against the live rules without signing anything. The result lists detected blockers and who can resolve them, such as a holder with a missing claim, a sender without enough transferable units, or an operator managing a freeze or a paused token. A frozen holder address counts as a blocker for transfers: the recipient-eligibility check reports it as not eligible with the reason address-frozen. A stale price requires a fresh feed update. The result describes current state. Execution can encounter later changes. Fix the blocker, re-check, then submit the real transfer.

How it works and what it covers

Transfer-path compliance runs as a check inside the token's own state-update path. Every ordinary way of moving the token ends in the same hook: a direct transfer, an allowance-based transfer or a batch item. Enforcement therefore does not depend on how the movement was submitted. The token standard extends ERC-3643, an open standard for permissioned security tokens.

An ordinary transfer first runs the recipient's identity check in the token's identity registry: registration, a wallet not marked lost and, where the registry holds one, its topic expression. The compliance engine then checks the recipient bypass list, the addresses, such as the platform's settlement and vault contracts, that skip the rules that judge a recipient. DALP manages the list: a token or add-on factory adds the contracts it deploys. On the second-generation compliance engines, a bypassed recipient skips, in both module layers, the rules that judge the recipient: country and identity lists, identity verification, claim expiry, holder counts and transfer approval. The address block list, time lock, lock-up, minimum holding, own custody gateway and supply rules still run. A first-generation engine skips every module for a bypassed recipient. Active modules evaluate the movement in scope, and the token engine then delegates to the global engine. A failing check reverts the transaction. A generic rejection may require simulation to identify the blocker.

One engine reads two layers from one catalogue.The token's compliance engine evaluates on every movement on the transfer path. It reads the platform's module catalogue of registered control types, which feeds two layers: the rules installed on this token, and the global controls installed once at the platform level. Every rule passing lets the transfer proceed. The first failure reverts it.One engine reads two layers from one catalogue.The same figure as the desktop variant, stacked for phone widths: the transfer path reaches the compliance engine, the engine reads the module catalogue, and the catalogue feeds both layers directly, rules installed on the token and global controls, each of which feeds forward to every movement, where every rule passing lets the transfer proceed while one failure reverts it.

One catalogue supplies both layers of controls, and a bypass-listed recipient skips only the modules that judge the recipient on a second-generation engine.

Modules are typed and instanced. A control type must exist in the platform catalogue before an engine can install it. Installing it deploys a fresh instance, so the same type can run more than once with different parameters. Each instance can limit its checks by sender, receiver, or country. Global rules can also select tokens by scope. The Compliance manager sets a global rule's scope. The token cannot change that selection.

After a successful movement, stateful rules update their records in the same transaction: holder counts, issuance windows, consumed approvals, lock batches. A failed update reverts the whole transfer, so rule state and balances stay in step while the rule is enabled. A small set of paths move value without evaluating those rules. Controls and evidence lists each one with what it still requires.

The integration contract

The API surfaces transfer-path compliance as three parts: configuration, simulation, and a failure contract. You install, configure, scope, disable, or remove compliance modules on a token or at the system level, and group modules into compliance templates you apply at asset creation.

Before submitting a transfer, simulate it. The transfer-simulate endpoint takes the sender, recipient, and amount and runs the same on-chain compliance check the transfer itself would run. It returns a verdict of will clear or will revert. On a revert it also returns a blocker list: the rule that fails, which party it applies to, the reason class, and who can remediate it. The endpoint signs and changes nothing, so call it as part of a pre-trade workflow.

Simulate first, then submit.The integrator first asks to simulate a transfer with the sender, recipient, and amount. The token answers with a clear verdict or the rules that block it, and the verdict returns to the integrator. Once ready, the integrator submits the real transfer under the same rules. The token executes it or reverts it, and the result settles on chain either way.Simulate first, then submit.The same figure as the desktop variant, stacked for phone widths: simulate resolves to a verdict, and once the integrator is ready, submit runs the real transfer under the same rules and settles on chain either way.

Simulating before submission shows current blockers, but the real transfer checks state at execution and can still fail after a clear simulation.

DALP-1096 reports a rejected transfer and DALP-1110 a rejected mint. Neither code alone identifies the failing layer. Inspect the simulation result and current policy. DALP-1111 identifies a stale-price blocker that needs a fresh feed update. Recheck after remediation. If a write was already accepted, read its outcome before deciding whether to retry the existing request or start a new attempt.

The token contract enforces the rules, and the API only reports them. An ordinary movement submitted through any client or a direct on-chain call passes the same checks. The forced-transfer and recovery routes skip the module checks, as Controls and evidence lists.

Read a transfer's verdict before signing

Call GET /api/v2/tokens/{assetId}/transfer-simulate?from={sender}&to={recipient}&amount={amount}. Any signed-in caller or API key can call it, and amount is an integer string in the token's base units. The call submits nothing and costs no fee. It reads the token's pause state, any freeze on either address, the sender's transferable units, the recipient's identity and the compliance rules bound to the token. Transferable units are the sender's balance less its frozen and held units.

The response holds data.verdict, either will-clear or will-revert, and data.blockers. Each blocker carries code, party (sender or recipient), reason, remediationClass and remediation, plus moduleTypeId and moduleInstance when a compliance module refused the transfer, and topics when a missing claim is the cause. When a rule that requires claims refused the party, ruleSource names it, and topics lists the claim topics missing for that rule:

  • token-registry is the rule stored in the token's identity registry.

  • identity-verification-module is the rule in the token's identity verification module, first or second generation.

  • global-control is the system's global identity verification control. Each rule that refuses gets its own blocker, so a party that fails two rules sees two blockers. A blocker that no module explains, such as a freeze, too few transferable units, a paused token or a restricted refusal, carries neither module field. A remediation of kind none carries a reason that says why. The remediationClass says who can resolve the blocker:

  • self-serve: the party can resolve it, for example by obtaining a claim the token requires or by holding enough transferable units.

  • operator: someone at the issuing institution must act, for example to unfreeze an address, remove an entry from a block list, register an identity, approve the transfer or unpause the token.

  • structural: the transfer cannot clear in its current shape, for example when no compliance module explains the refusal.

The verdict comes from live chain calls. When the transfer would revert, the platform adds the rule detail from its index of on-chain state, and that detail never changes the verdict. Rule-level detail goes only to a caller whose signing wallet holds the System manager, Identity manager, Verification issuer or Compliance manager role, or whose signing wallet is a custodian of the token. Any other caller sees freezes, a short balance and a paused token by name, and a single blocker with the code compliance-restricted for anything else.

The platform evaluates the identity and compliance rules only on a token the caller's organisation issued. On any other token the check covers the pause state, freezes and the sender's transferable units. A will-clear there says nothing about the token's rules. The check does not cover an allowance or a token feature that refuses the transfer, so a pass can still revert for those reasons.

A token that is not indexed on the caller's network answers not found. When the platform cannot read the chain or its index in time, the route answers DALP-12354, a retryable 503 with the message “The transfer check is temporarily unavailable”. That answer is not a verdict, so retry after a short wait.

Controls and evidence

Transfer-path compliance is preventive for the movements within its scope. A failed check reverts that transaction's balance changes. Governance must account for bypassed recipients, recovery paths, and policies that do not encode every legal requirement.

Enforcement reads on-chain state at execution time: a revoked claim or a new block-list entry binds at the next movement that needs it. The lag between an off-chain decision and the matching on-chain claim update is your operating responsibility. The platform enforces only what your process has already recorded.

You can read the evidence without reconstructing it. Each token shows its own modules plus the global controls that reach it, each marked “Global”, and one platform-level page shows the global policy. Each identity carries its claim history, with issuers, and simulation can identify the current transfer blockers. Keep personal evidence off-chain. Claim fields and identifiers are public, so review their contents before issuance. A claim records an issuer's attestation, and withdrawing trust in that issuer stops its claims from counting at the next movement, without touching the claims themselves.

Four paths move value without the full rule check, and each is recorded on chain:

  • Custodian forced transfer. Only the token's Custodian role can run it. It skips the compliance modules, the pause and the sender's freeze, refuses a recipient whose address is frozen, and still runs the recipient's identity check in the token's identity registry, topic expression included where the registry holds one. A topic rule applied through an identity verification compliance module does not run. The chain records it as a custodian operation.
  • Wallet recovery. An Identity manager records a wallet as lost and names its replacement, acting alone on chain. The platform's own recovery then moves each balance with the custodian's forced recovery call, under the same identity check. The replacement wallet can also claim the lost wallet's balance itself, so review who holds Identity manager as closely as Custodian.
  • Bypassed recipients. The platform's own settlement and vault contracts may receive assets without the rules that judge a recipient, while sender-side and supply rules still run on a second-generation engine. Ordinary transfers leaving them for a non-bypassed recipient pass the applicable checks. No Console screen or Platform API route edits the bypass list directly. A System manager can change the list by registering a custom token factory or add-on, or by pointing a registered one at new code, because every registered factory and add-on can add and remove addresses. A Compliance manager can change it with a direct call to the system compliance contract.
  • Burn. A burn skips eligibility checks because no one receives anything. Supply tracking rules record it after the fact, and the Supply management role can burn from any holder's wallet.

Three roles can change the check itself. The Governance role can replace a token's compliance contract and identity registry with a direct contract call, and change or turn off its modules. The System manager can replace the token logic that every token from a factory runs. A Compliance manager installs, scopes and removes global controls. Reviewing a token's effective policy means checking the bypass list and who holds Custodian, Governance, Identity manager, Supply management, System manager, Compliance manager and Escrow manager, beside the bindings.

Frequently asked questions

What happens when a holder loses eligibility after acquiring tokens?

The held balance stays where it is. Enforcement applies to movements, not to holdings. Once an issuer revokes a claim, the holder cannot receive more of any asset that requires it, and sender-scoped rules bind their outgoing transfers too. Freezing or moving the balance itself is a governed custodian decision, not an automatic consequence.

Can anyone get around the rules?

A custodian forced transfer and a wallet recovery skip module evaluation, the bypass list skips the rules that judge a recipient, and a burn skips eligibility. Controls and evidence lists the four paths and the roles that can change the rules themselves. A wallet cannot recover itself: recovery needs an Identity manager to record the wallet as lost and name its replacement, and that Identity manager can name a wallet they control. A direct on-chain transfer between two ordinary wallets runs the same checks as one submitted through the platform.

Does a clear pre-check guarantee the transfer will succeed?

No. The verdict only holds for the instant the simulation runs against live state, not as a lock on that state. Between the read and the signature, an issuer can revoke a claim or a Compliance manager can add a global control, and neither one waits for you to sign. Re-run the simulation immediately before submitting, especially after any delay for review, approval or a wallet's own signing prompt, because eligibility can move in that gap. The check also does not cover an allowance or a token feature that refuses the transfer, so a clear result can revert for those reasons too.

How is this different from checking compliance in the application before submitting?

An application-side check advises, while the token enforces. Because the rules run inside the token contract, they bind every submission path, including ones that never touch your application. Simulation inspects the applicable on-chain checks against current state. A later transfer can see different state or encounter another execution failure.

How do decisions from our KYC provider reach the chain?

A decision reaches the chain in one of two ways. A connected provider sends its verdict, and the issuer identity the platform provisioned for that provider signs or revokes the matching claim. Or your own reviewers complete the review, and an issuer you trust records the claim manually. Either way, enforcement reads the claim, and the attestation counts only when the registry trusts the issuer for that claim topic.

Who decides which rules an asset enforces?

Your organisation decides, split by role. Whoever holds the asset's Governance role picks and parameterises its modules, or applies a policy template, at issuance, and can change or turn them off at any time after. The Compliance manager, an organisation-wide role, is the only one who can install or scope a global control. The Verification policy manager decides which issuers count for each claim topic. The platform validates and enforces whatever that configuration says. It does not choose the policy or substitute for legal or regulatory judgment.

Was this page helpful?