J3. Transfer agent journey: operations on a live asset
The transfer agent is the operator that keeps the register of an asset on the Issuer's behalf. In the protocol it is a set of roles: the Token Agent roles on the token, and the Registry Agent role on the eligibility registry. They are typically held by one operator, which is the Issuer itself or a provider it appoints. This journey starts when the Issuer grants the agent roles. It has no end: it lists the situations an agent meets in the life of the asset, and the operation that answers each. An agent holds no tokens and no key of any holder. It holds roles, each of which opens specific functions.
Stages
The stages are situations, not a sequence. Stage 1 comes first. The others occur in any order.
1
Receive the agent roles
Issuer
The operator holds the roles of the operations it performs, in the Issuer's domain
2
A subscription is settled
Token Agent (AGENT_MINTER)
New units exist, credited to an eligible investor
4
A holder's address cannot link itself
Registry Agent (AGENT)
The address resolves to the holder's identity for this asset
5
A registration has to change
Registry Agent (AGENT)
The local record is corrected or deleted
6
Tokens have to be immobilized
Token Agent (AGENT_ADDRESS_FREEZER, AGENT_PARTIAL_FREEZER)
An address, or an amount on it, cannot move
7
A decision overrides the holder
Token Agent (AGENT_FORCED_TRANSFER)
Tokens move to an eligible recipient without the holder
8
A holder lost a wallet
Token Agent (AGENT_RECOVERY_ADDRESS)
The whole balance is at a new address of the same identity
9
An incident requires a halt
Token Agent (AGENT_PAUSER)
Movements between holders stop, then resume
Overview
What the persona sees and does
1. Receive the agent roles. The Issuer grants the operator the roles of the operations it performs, in the domain of the asset. The roles are separate: an operator that mints does not have to be able to freeze or to force a transfer. The operator checks what it holds with hasRole on the access manager, with the role identifier of the asset's domain. A role granted with an execution delay means each call is scheduled first and executed after the delay.
2. A subscription is settled. The Issuer confirms, under its own process, that an investor has paid for a subscription. The agent checks that the investor is eligible and that the rules of the asset allow the amount, then mints. The token applies the same two gates itself: a mint to an investor that is not eligible reverts. The agent decides that the mint happens. The token decides whether it is allowed.
3. A redemption is settled. The Issuer confirms a redemption, a buy-back or a cancellation. The agent burns the units at the holder's address. A burn needs no signature from the holder and passes no gate, since nothing is received. It releases frozen tokens when the free balance is not enough.
4. A holder's address cannot link itself. Most holders need nothing from the agent: an ONCHAINID, or a wallet its owner linked, is recognized by every asset. The agent registers an address only when it cannot link itself and has to hold the asset: a custody account, a contract that cannot sign, an omnibus wallet, recorded under the entity that operates it. The registration is local to the asset. The agent keeps the evidence that the address belongs to the identity, because the contract takes its word.
5. A registration has to change. A local registration made under the wrong identity is corrected. A registration that is no longer needed is deleted, and the address falls back to its global link if it has one. An update changes who the tokens at that address are attributed to, without any transfer. A removal does so only when the address is linked globally to another identity. The agent treats both as carefully as a movement.
6. Tokens have to be immobilized. An investigation, a lock-up, a pledge, a compromised wallet. The agent freezes an address entirely, so that it neither sends nor receives, or freezes an amount on it. The tokens stay owned by their holder. The agent unfreezes when the cause is gone.
7. A decision overrides the holder. A court order, a succession, the correction of an error. The agent moves the tokens itself. A forced transfer goes through freezes and does not ask the compliance rules. It keeps one gate: the recipient must be eligible. The agent records the decision that justifies it, since the contract executes whatever the role allows.
8. A holder lost a wallet. A holder that still controls its ONCHAINID moves its free tokens itself, through its identity. The agent acts when the holder cannot, or when the lost wallet holds frozen tokens. It moves the whole balance, with its freezes, to another address of the same identity. The holder's identity, claims and eligibility are untouched.
9. An incident requires a halt. The agent pauses the token. Transfers between holders revert until it lifts the pause. Mints and burns still work during a pause. Forced transfers and recoveries do not: to run one, the agent lifts the pause, acts, and pauses again if needed. The token can also pause itself when the cross-chain layer delivers a settlement the register cannot account for: the response is in 36.
Where journeys diverge
The position is active on a satellite. An agent cannot freeze, burn or force a transfer on a satellite. It recalls the position to the reference chain first: 32.
A holder must leave the asset. The operations of stages 6, 7 and 3 are chained in a set order: J5.
A holder lost the keys of its identity, not a wallet. The agent has no authority over an identity. The holder's guardians recover it: 21. If that is not possible, the agent moves the positions of its asset to a new identity with stage 7.
A holder became ineligible. Nothing happens to its position. It keeps it, can still send to an eligible recipient and cannot receive. The Issuer decides whether to freeze: stage 6.
A validation is stuck. The release of reservations is the Validation Keeper's work, not the agent's: 35.
Related journeys
J1 Issuer journey: launch an asset : how the asset came to be live
J5 Offboarding journey: an investor that must no longer hold or receive : the agent operations chained for an exclusion
J4 Cross-chain journey: distribute and reconcile : the same asset on satellites