Holder Eligibility and Transfers

A regulated asset cannot move to just anyone. XKOVA keeps an eligibility store of accreditation and jurisdiction per holder and lockups per holding, then runs a graded transfer door that evaluates every move against that store, the cap table, and any lifecycle freeze, before the relayer ever spends gas.

The eligibility store

Two kinds of facts govern who may hold and move a token: attributes about the holder, and lockups on a specific holding.

Holder attributes

A holder's global attributes are accreditation status and jurisdiction, keyed by (workspace, holder). There is one row per holder, and a repeat write overwrites it. Accreditation status is one of none, self_attested, verified, or expired, with an optional expiry timestamp. The source records where the attribute came from: a KYC provider, an operator attestation, or an integrator-supplied value. A holder is identified either by an account-holder id or a raw wallet address (case-insensitive; an address is lowercased server-side).

Per-holding lockups

A lockup pins a release instant on a specific (token, holder) pair: the holder cannot move that token until the lockup expires. There is one lockup row per (token, holder); a repeat write overwrites it. A lockup carries an operator-supplied reason and is recorded as a compliance action.

Reading the context

Reading the (token, holder) eligibility context returns exactly what the transfer door consumes: the holder's effective accreditation, their jurisdiction, and the lockup release instant for that holding. When no attribute or lockup row exists, accreditation reads none and the other fields are null. Setting holder attributes and lockups requires the token admin role.

The graded transfer door

Every governed transfer of a real-world-asset token passes through one decision point before any gas is spent. This is the graded transfer-eligibility door. It evaluates a set of predicates over the eligibility store, the cap table, and any lifecycle freeze, and returns a binary allow or deny verdict. Two transfer paths both run it:

• Gasless holder transfer: the holder signs an ERC-2771 forward request to move their own NFT without paying gas. The api builds the request, the holder signs it, and on submission the api recovers the signer, runs the door, then runs a separate fail-closed sanctions screen of the recipient, and only then has the XKOVA Relayer submit the move and pay gas.
• Treasury Safe transfer: an issuer moves an asset the treasury Safe owns, via the N of M signer flow. The door runs at draft time, before signers approve.

What the door checks

Predicate	Reads
Accreditation / jurisdiction	The effective holder attributes for the recipient.
Lockup	The per-holding release instant; a move before it is denied.
Holder cap	The cap table, to enforce a maximum distinct-holder count where a template defines one.
Lifecycle freeze	Whether the token or instance is frozen by a running corporate action.

If a predicate rejects the move, the transfer is denied with a clear reason (an eligibility denial for a holder-cap, lockup, or jurisdiction rule, or a transfer-frozen denial for a lifecycle freeze) and no gas is spent. The door runs before the relayer, so an ineligible move costs nothing on-chain.

Sanctions screening of the recipient address is a separate, fail-closed gate that runs after the door and before the relayer submits. It denies with its own screening reason, distinct from an eligibility denial, so a blocked move tells you which control stopped it.

flowchart TD
  A[Signed transfer request] --> B{Transfer eligibility door}
  B -- holder cap, lockup, jurisdiction, accreditation --> X[Denied with an eligibility reason, no gas spent]
  B -- lifecycle freeze active --> X2[Denied as transfer frozen]
  B -- allow --> C{Sanctions screen of the recipient}
  C -- match, or screen cannot complete --> X3[Denied, fail closed]
  C -- clear --> D[XKOVA Relayer submits the move and pays gas]

Where the rules come from

Some eligibility rules are not set per holder at all but baked into the asset schema. A share-class template can declare a transfer-eligibility rule (for example, that a transfer requires the recipient be accredited), which the schema compiler turns into a predicate the door evaluates. That keeps the policy with the asset definition rather than scattered across individual writes. See Real-World Assets for the schema model.

Related

• Cap Tables and Distributions: the positions the holder-cap predicate reads.
• Corporate Actions: the lifecycle freezes the door honors.
• Treasury: the N of M Safe flow the treasury transfer path uses.
• Screening (KYT and BSA): the sanctions providers behind the egress check.
• Non-custodial Model: why the holder signs and the relayer submits.