# How REAL fits together (/docs/architecture)
## A shared financial record [#a-shared-financial-record]
REAL's design keeps the authoritative financial record on its dedicated chain. Asset terms, identity checks, settlement events, risk assessments, and validation history can refer to the same asset, allowing services to coordinate throughout its lifecycle. Connections to other networks extend access while REAL retains its own network policy and authoritative state.
Shared records make actions traceable. Contracts apply configured rules; the parties submitting external information remain responsible for its accuracy.
## Follow an asset [#follow-an-asset]
1. **Network — Real Chain** executes transactions and records shared state.
2. **Asset — Tokenization Engine** applies token, identity, and compliance rules.
3. **Accountability — Business Validators** perform assigned services backed by stake and enforcement.
The layers share records, not interchangeable authority. The example below follows one bond across them; BV assignments and insurance apply only where explicitly configured.
Consider an issuer representing a bond as a permissioned token. The bond's terms establish the rights and obligations. REAL's systems provide different parts of the infrastructure used to record and operate that asset.
### 1. Configure the asset token [#1-configure-the-asset-token]
The issuer sets up a token suite: a group of contracts covering the token, identity checks, and transfer rules. Authorized participants configure who can operate the suite and the eligibility requirements that apply to investors.
### 2. Establish investor eligibility [#2-establish-investor-eligibility]
An investor's wallet is associated with an identity. Claims from trusted parties attest to relevant facts, such as completion of an identity check. Each suite determines which claims it requires and which claim issuers it accepts. Reusing an identity does not automatically make an investor eligible for every asset.
### 3. Execute token operations [#3-execute-token-operations]
When a transaction reaches Real Chain, the network executes the relevant contracts. For an ordinary token transfer, the token and its connected contracts check the applicable identity requirements, transfer restrictions, and token state before balances can change.
A confirmed transaction establishes what the contracts executed. It does not independently establish the truth of every underlying business fact or fulfil an issuer's obligations outside the chain.
### 4. Carry out assigned business responsibilities [#4-carry-out-assigned-business-responsibilities]
For assets connected to the Business Validator Protocol, assigned participants take on tokenization, scoring, or insurance responsibilities. The protocol defines how those responsibilities relate to stake, rewards, and enforcement. Participation and coverage depend on the asset's assignments and the integration in use.
An insurance role does not mean every tokenized asset is insured. In the protocol design, stake supports accountability; insurance payouts are a separate obligation funded by the insurance participant.
## Keep authority separate [#keep-authority-separate]
| Participant or role | Responsibility | Boundary |
| ------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| Network validator | Participate in chain consensus | Does not receive issuer or token-management powers from this role |
| Issuer workspace administrator | Perform authorized platform operations | A platform account alone does not grant contract permissions |
| Contract owner or agent | Configure or operate contracts within assigned permissions | Authority is specific to the contract and role |
| Claim issuer | Attest to facts used in identity checks | A suite must trust that issuer for the relevant claim |
| Business Validator | Carry out assigned protocol responsibilities | Admission does not automatically grant token-agent authority |
One organization may hold several roles. Each role still needs its own authorization and has its own responsibilities.
## Choose the system you need [#choose-the-system-you-need]
* [Real Chain](/docs/chain) explains network infrastructure and execution.
* [Tokenization Engine](/docs/tokenization) explains permissioned assets and issuer operations.
* [Business Validator Protocol](/docs/business-validators) explains business responsibilities and enforcement.
# REAL overview (/docs)
## What is REAL? [#what-is-real]
REAL is building a financial network that brings network operation, asset rules, and accountable services into one operating model. Its dedicated chain is part of the financial product: it gives REAL control over validator participation, fees, execution capacity, and the governance of network changes.
## Three layers of the financial network [#three-layers-of-the-financial-network]
### Real Chain [#real-chain]
Real Chain is the network layer: a dedicated Layer 1 compatible with the Ethereum Virtual Machine (EVM). It gives REAL its own validator set, blockspace, fee policy, and upgrade path for the financial applications built on it.
### Tokenization Engine: the asset layer [#tokenization-engine-the-asset-layer]
The Tokenization Engine supports permissioned asset tokens using ERC-3643, a token standard with identity and transfer controls. It brings together token contracts, investor identities, trusted claims, and configurable rules. Issuers and authorized operators use these components to manage the token through its lifecycle.
### Business Validator Protocol: the trust layer [#business-validator-protocol-the-trust-layer]
The Business Validator Protocol defines responsibilities for tokenization, scoring, and insurance participants. Its design connects assigned work to stake, rewards, and enforcement. These are business responsibilities associated with assets; they are separate from validating the network's blocks.
## Who these docs are for [#who-these-docs-are-for]
| Reader | Main questions |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| Issuers and asset operators | How is an asset represented, who can hold it, and who may manage it? |
| Investors | What can I acquire, what can the issuer change, and how do verification and recovery work? |
| Institutions and compliance teams | Who controls upgrades, identities, and external inputs, and what review evidence exists? |
| Application developers and integrators | How do the network, token contracts, and identity rules fit together? |
| Business Validator participants | Which responsibilities belong to each role, and how does accountability work? |
| Network operators | What is the network's role, and how does it differ from asset operations? |
## How to read this edition [#how-to-read-this-edition]
Start with the system architecture on the next page, or follow the path that matches your task:
* **Investor:** [investor workflow](/docs/tokenization/investor-workflow) → [offerings](/docs/tokenization/offerings) → [secondary trading](/docs/tokenization/secondary-trading).
* **Issuer:** [issuer workflow](/docs/tokenization/issuer-workflow) → [asset information](/docs/tokenization/asset-information) → [token operations](/docs/tokenization/operations).
* **Institution or compliance team:** [trust model](/docs/resources/trust-model) → [security and audits](/docs/resources/security-and-audits) → [identity rules](/docs/tokenization/identity).
* **Business Validator:** [admission preparation](/docs/business-validators/become-a-validator) → [protocol parameters](/docs/business-validators/parameters) → [worked examples](/docs/business-validators/examples).
* **Developer or integrator:** [networks](/docs/chain/networks) → [tested quickstart](/docs/chain/build) → [platform integration](/docs/tokenization/integration).
* **Network operator:** [network architecture](/docs/chain/architecture#network-validators). This role is separate from Business Validator participation.
Testnet references state their verification date and environment. [Documentation status](/docs/resources/documentation-status) tracks remaining production and operational gaps.
# Become a Business Validator (/docs/business-validators/become-a-validator)
## 1. Choose the responsibility [#1-choose-the-responsibility]
Select the [role or roles](/docs/business-validators/roles) your organization can perform. Prepare an asset-maintenance process for TV work, a documented scoring methodology for SV work, or underwriting and claims operations for IV work.
The commitment is ongoing. Plan for missed deadlines, staff changes, disputes, and eventual transfer of the portfolio as well as the initial registration.
## 2. Confirm admission [#2-confirm-admission]
The registry supports allowlisted registration and initializes in that mode. Governance controls admission settings. Confirm the current process and operator authorization for the intended deployment before attempting to register.
Creating an issuer-portal account, adding Real Testnet to a wallet, or receiving faucet tokens does not admit an operator as a Business Validator. These docs do not provide an open self-service admission route.
## 3. Prepare identity and signing [#3-prepare-identity-and-signing]
Registration associates an operator address, legal-entity reference, and selected roles with a [BVID](/docs/resources/glossary#bvid). Use a signing arrangement your organization can operate and recover reliably. The protocol supports operator rotation without creating a new BVID.
For testnet preparation, [add Real Testnet to your wallet](/docs/chain/wallet-setup). Keep transaction gas available separately from the ASSET you intend to post as collateral.
## 4. Fund the role [#4-fund-the-role]
Size collateral against the portfolio you intend to serve, using the deployment's current stake requirements and ASSET valuation. Check each role independently. A registered identity alone is not sufficient to accept new volume.
Read [Stake and lifecycle](/docs/business-validators/lifecycle) before depositing. [Treasury delegation](/docs/business-validators/delegation) is a separately controlled facility, not an automatic entitlement for applicants.
## 5. Connect operations and monitoring [#5-connect-operations-and-monitoring]
Before accepting assets, verify that your team can submit role-specific actions, monitor obligations, and respond to an adverse event. Assign ownership of metadata updates, scoring deadlines, claims, collateral top-ups, and dispute responses as applicable.
Use the [testnet dashboard](https://testnet.dashboard.real.finance) to inspect exposed protocol state and the [block explorer](https://testnet.explorer.real.finance) to check transactions. [Integration and monitoring](/docs/business-validators/integration) explains how to reconcile these views with the contracts.
## Ready to accept obligations [#ready-to-accept-obligations]
Proceed when admission, the registered role, collateral capacity, and the service workflow are confirmed for the deployment. Use the [contract reference](/docs/resources/testnet-contracts) for verified addresses. A public admission contact and end-to-end registration procedure remain pending in [Documentation status](/docs/resources/documentation-status).
# Treasury delegation (/docs/business-validators/delegation)
## Purpose and access [#purpose-and-access]
[Treasury delegation](/docs/resources/glossary#treasury-delegation) lets a governance-designated treasury back a Business Validator's role with ASSET. It is a controlled bootstrap facility, not a public market where any token holder can delegate to an operator.
The implementation requires a global enablement setting, a configured treasury address, operator consent for the role, and an eligible validator state. Repository support does not establish that these settings are enabled in a particular deployment.
## Ownership and responsibility [#ownership-and-responsibility]
Treasury and operator collateral contribute to the account's capacity, but ownership remains separate. Delegating funds does not transfer the operator's signing authority or business responsibilities to the treasury.
The facility permits full treasury backing. An operator with no self-stake has no direct capital to lose in a slash; the treasury bears that exposure. Rewards are divided according to age-weighted collateral ownership, so a fully treasury-funded account does not give the operator staking rewards merely for running it.
## Buying out the treasury [#buying-out-the-treasury]
The operator can pay ASSET to convert active treasury positions into self-owned stake at par. The collateral stays posted and its age is preserved. This changes ownership and future reward allocation without withdrawing and redepositing the collateral.
Buy-out is blocked by applicable open disputes and provisional reservations. Treasury positions already in unbonding are exiting and cannot be bought out through this path.
## Loss and exit [#loss-and-exit]
The reviewed delegation model puts operator self-stake first in the loss order, followed by treasury collateral. Both owners can lose capital; treasury backing is not protected principal.
A treasury exit immediately removes the exiting amount from posted capacity, which can reduce the validator's health. Funds then pass through the configured unbonding period and remain exposed until release. The operator's own withdrawal path is different and retains its requirement, reservation, and lifecycle gates.
Delegated collateral does not itself receive dispute or governance voting weight. Moving treasury support between operators requires an exit and a new delegation, rather than carrying the old position's age into another account.
## Before relying on the facility [#before-relying-on-the-facility]
Verify the deployed implementation and current settings, including pending liabilities and the release path. Detailed attribution of losses across changing positions is release-sensitive; these pages do not certify a pending collateral-accounting upgrade or a live treasury allocation.
# Worked examples (/docs/business-validators/examples)
## Collateral for a $20M portfolio [#collateral-for-a-20m-portfolio]
Assume one role carries $20M of outstanding [notional](/docs/resources/glossary#notional). Apply the [verified marginal tiers](/docs/business-validators/parameters):
| Band | Calculation | Required collateral |
| -------------- | ---------------------- | ------------------- |
| First $1M | $1M × 5% | $50,000 |
| Next $9M | $9M × 3.5% | $315,000 |
| Remaining $10M | $10M × 2.5% | $250,000 |
| Total | Sum of the three bands | **$615,000** |
At an **illustrative** [oracle](/docs/resources/glossary#oracle) price of $0.25 per ASSET, the requirement is **2,460,000 ASSET**. This price is an assumption, not a current quote. An operator posting exactly that amount begins at 100% collateral health before reservations or other restrictions.
If price falls to $0.20, the same stake is worth $492,000, or **80%** of the requirement. Under the ordinary health thresholds it becomes degraded. Restoring 100% requires another $123,000, equivalent to **615,000 ASSET** at that price. SV top-up grace can affect the reported state; raw collateral coverage remains 80%.
## One reward epoch [#one-reward-epoch]
Assume an illustrative, fully funded [epoch](/docs/resources/glossary#epoch) slice of **9,000 ASSET**, no carryover or rounding residue, all three role floors active, and no eligibility reductions. Each role has at least three qualifying validators and $5M notional. This is an allocation example, not the promised slice for the current three-hour epoch.
Each role first receives its 20% floor: **1,800 ASSET**. That leaves **3,600 ASSET** to divide by effective weight. Suppose total effective weights are 180,000 for TV, 90,000 for SV, and 90,000 for IV:
| Role | Floor | Share of remaining pool | Total |
| ---- | ----- | ----------------------- | --------- |
| TV | 1,800 | 1,800 (50%) | **3,600** |
| SV | 1,800 | 900 (25%) | **2,700** |
| IV | 1,800 | 900 (25%) | **2,700** |
Within TV, consider an operator with $100,000 posted stake value, weighted stake age **A = 12 months**, **N = 50** distinct assets served, and **n = 1** counted offence in the trailing 12 months:
* Age multiplier: `A / (A + 12) = 0.5`.
* Experience multiplier: `1 + 2N / (N + 50) = 2`.
* Reputation multiplier: `max(0.5, 1 − 0.1n) = 0.9`.
* Weight before eligibility gates: `100,000 × 0.5 × 2 × 0.9 = 90,000`.
Assuming this operator is eligible and the two other TV weights are 45,000 each, its share is **50% × 3,600 = 1,800 ASSET**. Treasury-backed positions can split an account's accrual further. Actual calculation uses fixed-point arithmetic, snapshots, eligibility gates, and funding checks; read [Rewards](/docs/business-validators/rewards).
## One Brier evaluation [#one-brier-evaluation]
Assume **100 eligible assets**, all predicted at **10%** probability of default, and **30** observed defaults within the defined outcome horizon. Each asset has an in-scope scheduled payment, and the evaluation time has arrived.
1. Observed score: `(30 × 0.9² + 70 × 0.1²) / 100 = 0.25`.
2. Expected score: `0.1 × 0.9 = 0.09`.
3. Implemented standard error: `sqrt(0.09 × (1 − 0.09) / 100) ≈ 0.028618`.
4. With multiplier 2, the threshold is `0.09 + 2 × 0.028618 ≈ 0.147236`.
Because **0.25 exceeds 0.147236**, the evaluation reports a breach and enters the provisional penalty process. This uses the protocol's implemented standard-error formula. It is not a claim that every statistical calibration method uses that formula.
A sample below the configured minimum of 30 would be skipped rather than counted as successful calibration. Assets without an in-scope payment are excluded. See [Scoring Validator](/docs/business-validators/scoring) for outcome timing and [Penalties and disputes](/docs/business-validators/mechanisms) for what follows a breach.
# Business Validator Protocol (/docs/business-validators)
## Accountability beyond the token [#accountability-beyond-the-token]
A token records ownership. It does not establish that an asset description is accurate, a risk estimate is useful, or an insurer will pay. The Business Validator Protocol assigns these responsibilities to identified operators and connects their conduct to collateral, rewards, and penalties.
It works alongside the Tokenization Engine. The engine controls the asset's on-chain lifecycle; Business Validators maintain asset information, publish risk assessments, and take on insurance obligations. [Network Validators](/docs/chain/architecture#network-validators) separately secure transaction execution and consensus.
## Three responsibilities [#three-responsibilities]
| Role | Responsibility |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [Tokenization Validator (TV)](/docs/business-validators/tokenization-validator) | Register and maintain the protocol's asset record |
| [Scoring Validator (SV)](/docs/business-validators/scoring) | Publish default-probability estimates and maintain a declared methodology |
| [Insurance Validator (IV)](/docs/business-validators/settlement) | Underwrite specified obligations and meet covered claims |
An operator can hold more than one role. Each role has a separate stake account and its own obligations. Read [Validator roles](/docs/business-validators/roles) for the authority and limits of each.
## How accountability works [#how-accountability-works]
An operator registers a Business Validator identity, backs its role with ASSET, and accepts a portfolio of obligations. The protocol tracks stake health and service records. Contract-verifiable failures enter a challengeable penalty process; claims requiring external evidence go through disputes. Rewards reflect participation, history, and eligibility. Exit requires resolving or transferring the remaining responsibilities.
The cashflow and calibration model is built around assets with scheduled payments, such as fixed-maturity loans and bonds. It should not be assumed to cover every asset class without adaptation.
## Choose your next step [#choose-your-next-step]
* **Participate:** [Become a Business Validator](/docs/business-validators/become-a-validator).
* **Assess the economics:** [Stake and lifecycle](/docs/business-validators/lifecycle), then [Rewards](/docs/business-validators/rewards).
* **Understand enforcement:** [Penalties and disputes](/docs/business-validators/mechanisms).
* **Build an integration:** [Integration and monitoring](/docs/business-validators/integration).
Use [protocol parameters](/docs/business-validators/parameters) and [worked examples](/docs/business-validators/examples) to assess collateral and rewards. [Documentation status](/docs/resources/documentation-status) tracks remaining operational gaps.
# Integration and monitoring (/docs/business-validators/integration)
## Contracts record the authoritative state [#contracts-record-the-authoritative-state]
Business Validator writes are role-scoped contract actions signed by an authorized operator or submitted through a permitted public entry point. The indexed API and dashboard make those records easier to inspect; they do not replace the contract's authorization checks.
Separate transaction submission from confirmation. After a write, inspect the receipt and resulting state, then allow for the indexer to catch up before expecting the dashboard to match.
## Start with the testnet tools [#start-with-the-testnet-tools]
* [Dashboard](https://testnet.dashboard.real.finance): inspect the protocol information exposed by the application.
* [Block explorer](https://testnet.explorer.real.finance): inspect transactions, logs, and deployed contracts.
* [Network metadata](https://testnet.api.real.finance/v1/meta): inspect the API's environment metadata.
* [Endpoint directory](/docs/chain/networks#developer-endpoints): find the REST API and application event WebSocket.
Confirm the chain and release before signing. A wallet connection and an API response do not prove that a [BVID](/docs/resources/glossary#bvid) has been admitted or that a role can accept new volume.
## Monitor obligations, not just balances [#monitor-obligations-not-just-balances]
| Area | Information to track |
| ---------------- | ---------------------------------------------------------------------------- |
| Identity | Current operator, roles, and BVID status |
| Collateral | Posted and withdrawable stake, reservations, health, price freshness |
| Asset service | Metadata events, re-attestations, scoring coverage, and liability portfolios |
| Scoring | Publication cadence, evaluable cohorts, and completed evaluation results |
| Insurance | Policy ownership, expiry, claim state, and full-payment status |
| Enforcement | Provisional penalties, dispute deadlines, and final outcomes |
| Exit and rewards | Auction progress, remaining obligations, finalized epochs, and claims |
The protocol read API covers validators, assets, policies, claims, obligations, calibrations, disputes, reward epochs, auctions, and events. Use the [verified contract reference](/docs/resources/testnet-contracts) for direct reads. A complete endpoint/schema catalogue remains pending.
## Keepers provide progress [#keepers-provide-progress]
Many checks require a transaction after a deadline. Keepers watch for these conditions and submit calls that the contracts verify. They help the protocol progress; they do not make elapsed wall-clock time execute a transaction by itself.
Distinguish these calls from privileged inputs. Payment reporting and price updates use authorized sources. A general statement that all off-chain services are trustless would hide these dependencies.
## Handle delayed and repeated observations [#handle-delayed-and-repeated-observations]
The indexer tracks canonical blocks and rebuilds projections after a detected reorganization. The application WebSocket supports event delivery, but it is not the chain's Ethereum subscription endpoint.
Reconcile against current state after a reconnect, avoid treating repeated events as new obligations, and record transaction and case identifiers in your operations system. An alert should point to a specific payment, penalty, dispute, or auction that an operator can inspect and act on.
# Stake and lifecycle (/docs/business-validators/lifecycle)
## What stake backs [#what-stake-backs]
Business Validators post native ASSET into a separate account for each role. Required collateral is calculated from the role's aggregate asset [notional](/docs/resources/glossary#notional): the principal or face value under responsibility, rather than the sum of future interest payments.
The requirement uses marginal tiers. Each band of notional has its own rate; crossing a band does not reprice the entire portfolio. When an obligation leaves, the reduction is the difference between the portfolio requirement before and after removal.
Requirements are denominated in USD while collateral is held in ASSET. Changes in the protocol's ASSET valuation can therefore change health even if neither the portfolio nor the token balance changes.
## Health and status answer different questions [#health-and-status-answer-different-questions]
**Stake health** describes collateral capacity for a role. **[BVID](/docs/resources/glossary#bvid) status** describes whether the operator is active, jailed, winding down, wound down, or banned. An account can be adequately collateralized and still be blocked by its status or a penalty freeze.
| Health state | Practical meaning |
| ------------ | ------------------------------------------------------------------------------------------- |
| Normal | Meets the configured collateral threshold; other admission and operation checks still apply |
| Degraded | Below normal collateral requirements; new volume is restricted and reward weight is reduced |
| Inactive | Below the lower threshold; no ordinary active-participation rewards or new volume |
Existing obligations continue when health deteriorates. A top-up or a reduction in outstanding liabilities can restore capacity. A low balance alone does not erase an insurance policy or discharge an asset-maintenance responsibility.
The protocol also exposes price freshness. Its health view retains the last available valuation when the feed is stale; operations such as withdrawals and reward processing have additional freshness checks. Scoring coverage has a specific top-up grace mechanism, so the raw ratio and reported health state should both be inspected.
## Price and keeper dependencies [#price-and-keeper-dependencies]
One address held the price-setter role at testnet block 4503, checked on 17 September 2026. The reviewed feeder implementation uses CoinGecko and a six-hour default polling interval; the running service's configuration was not inspected. The contract trusts the authorized submitted value rather than independently querying CoinGecko or aggregating a quorum of data providers.
The verified guards were a 20% maximum ordinary price step, a one-hour update cooldown, and a seven-day maximum price age. The [timelock](/docs/resources/glossary#timelock) can freeze the [oracle](/docs/resources/glossary#oracle) or force an update outside ordinary step/cooldown checks. `latest()` returns price, timestamp, stale status, and frozen status; it is not a Chainlink AggregatorV3 interface.
A sustained decline in ASSET/USD can reduce many validators' collateral health together. A [keeper](/docs/resources/glossary#keeper) outage can leave prices or lifecycle processing stale even while the chain remains reachable. Track price age and transaction results alongside balances. [Protocol parameters](/docs/business-validators/parameters) gives the dated settings.
## Posted and withdrawable balances [#posted-and-withdrawable-balances]
Withdrawable self-stake is constrained by the portfolio requirement and reservations for disputes and provisional penalties. Wind-down and pending insurance-book transfers impose additional restrictions. The operator cannot withdraw treasury-owned collateral as its own.
A reservation sets aside collateral for a possible debit. It reduces withdrawal capacity without itself changing the health calculation into a completed slash.
## Leaving takes more than withdrawing [#leaving-takes-more-than-withdrawing]
Voluntary exit starts a [wind-down](/docs/business-validators/wind-down). Responsibilities must mature, be replaced, or pass through the relevant resolution process. Asset service can stop before the associated collateral liability ends.
Self-stake withdrawals and treasury undelegation use different paths. Do not apply a treasury unbonding period to all operator withdrawals; see [Treasury delegation](/docs/business-validators/delegation).
# Penalties and disputes (/docs/business-validators/mechanisms)
## Two ways a case begins [#two-ways-a-case-begins]
Some failures can be checked against contract state: an overdue update, a calibration result, or an unpaid claim after its deadline. A caller triggers the check; the contract verifies the condition.
Other allegations require external evidence. Whether an asset record misrepresents an instrument or underwriting was fraudulent cannot be decided from a timestamp alone. Those claims enter a bonded dispute and vote.
## Automatic does not mean immediately final [#automatic-does-not-mean-immediately-final]
A contract-verified offence creates a **provisional penalty**. It records the assessment and reserves collateral while applying restrictions such as jail, a new-volume freeze, and a reward freeze. The final stake debit and associated recovery or forced-exit effects wait for resolution.
The current [BVID](/docs/resources/glossary#bvid) operator can challenge an eligible provisional penalty within its challenge window. If unchallenged, it can be finalized after that window. A challenge follows the dispute process; reversal releases the reservation and reverses the provisional contribution. Other independent restrictions may still apply.
This distinction matters in dashboards: an observed offence, an open challenge, and a completed slash are different states.
## Penalty progression [#penalty-progression]
1. **Detected offence:** a contract verifies the reported condition.
2. **Provisional penalty:** collateral is reserved and applicable restrictions begin.
3. **Resolution branch:** no challenge within the window permits finalization; a valid challenge enters the dispute process.
4. **Final outcome:** an upheld penalty proceeds to final enforcement; reversal releases its reservation and reverses its provisional contribution. Other restrictions can remain.
## How disputes resolve [#how-disputes-resolve]
A filer identifies a supported claim and posts an ASSET bond. The protocol derives the contested amount from the referenced records. Voting uses eligible locked positions from before the filing block, so acquiring voting power after filing does not change that dispute's snapshot.
Quorum and approval are separate checks: turnout uses raw eligible participation against the supply snapshot, while the result uses weighted votes. Challenges to contract-verified penalties require a stronger approval threshold. Large cases can enter an additional review and Overturn stage.
The filer must inspect the case's actual deadlines, bond, and state. A failed allegation, a lack of quorum, and a successful challenge need not route bonds or collateral in the same way. Dispute-derived rulings do not start another automatic-penalty challenge cycle.
## Consequences depend on the failure [#consequences-depend-on-the-failure]
The penalty ladder escalates repeated offences through jail, longer jail, and slashing. Some calculated debits apply without waiting for the ordinary flat-penalty slash rung; fraud and severe insurance failures can trigger stronger consequences and forced exit.
A slash can exhaust the role's available collateral. A larger assessed loss does not create additional recoverable ASSET. Enforcement records should distinguish the assessment from what was actually collected.
## What to monitor [#what-to-monitor]
Track provisional penalties and dispute IDs, response deadlines, reserved collateral, final outcomes, and transaction receipts. Restore operational compliance as well as collateral: adding stake does not dismiss a dispute or undo a confirmed offence.
The protocol uses governance-controlled parameters for relevant thresholds and windows. This conceptual guide does not publish a fixed penalty-price table as if it were the configuration of every deployment.
# Protocol parameters (/docs/business-validators/parameters)
## Scope and units [#scope-and-units]
These governance-controlled values were read from GovernanceParams on **Real Testnet, chain 117711, block 4503**, on **17 September 2026**. They describe that snapshot, not promised production settings. USD amounts use 18 decimal places internally; ASSET amounts use native-token base units with 18 decimals. Ratios use 18-decimal fixed-point values (WAD); durations are stored as seconds.
The [contract reference](/docs/resources/testnet-contracts) identifies GovernanceParams and its [timelock](/docs/resources/glossary#timelock). To reproduce a read, call `getUint(bytes32)` with the key encoded as a right-zero-padded ASCII string, **not a hash**. The tables show human-readable conversions.
## Marginal collateral tiers [#marginal-collateral-tiers]
| Aggregate role notional | Rate on that band | Parameter keys |
| ------------------------ | ----------------- | ------------------------------ |
| First $1M | 5% | TIER\_BOUND\_1 / TIER\_RATE\_1 |
| Above $1M through $10M | 3.5% | TIER\_BOUND\_2 / TIER\_RATE\_2 |
| Above $10M through $100M | 2.5% | TIER\_BOUND\_3 / TIER\_RATE\_3 |
| Above $100M | 1.5% | TIER\_RATE\_4 |
Each band applies only to the [notional](/docs/resources/glossary#notional) inside it. A $20M portfolio requires $615,000 of collateral before other constraints; see [worked examples](/docs/business-validators/examples).
## Health and enforcement [#health-and-enforcement]
| Setting | Testnet value | Key |
| ------------------------------------ | -------------------------------- | ----------------------------------- |
| Normal health threshold | 100% of required collateral | HEALTH\_NORMAL |
| Inactive threshold | Below 40% of required collateral | HEALTH\_INACTIVE |
| Jail / long jail | 7 / 30 days | JAIL\_DURATION / LONGJAIL\_DURATION |
| Provisional-penalty challenge window | 7 days | PENALTY\_CHALLENGE\_WINDOW |
| Dispute bond floor | 100,000 ASSET | BOND\_FLOOR |
| Entity ban duration | 1,825 days (five 365-day years) | ENTITY\_BAN |
The bond floor is a minimum, not the price of every dispute. Calculated bonds, assessed penalties, available collateral, and collected amounts are different quantities. The ban setting is finite, rather than “permanent.”
## Scoring, insurance, and exit [#scoring-insurance-and-exit]
| Setting | Testnet value | Key |
| ---------------------------------- | ------------------ | ------------------------------------------- |
| Minimum eligible scoring sample | 30 | CALIBRATION\_MIN\_N |
| Brier standard-error multiplier | 2 | BRIER\_SE\_MULT |
| Cohort window / prediction cadence | 90 / 90 days | CALIBRATION\_WINDOW / PD\_CADENCE |
| Forward outcome horizon | 365 days | PD\_HORIZON |
| IV payout / nonpayment windows | 48 hours / 30 days | IV\_PAYOUT\_WINDOW / IV\_NONPAYMENT\_WINDOW |
| TV / SV exit notice | 90 / 90 days | NOTICE\_TV / NOTICE\_SV |
| Minimum IV exit notice | 180 days | NOTICE\_IV\_MIN |
| Treasury delegation enabled | No (0) | DELEGATION\_ENABLED |
| Minimum delegation tranche | 10,000 ASSET | DELEGATION\_MIN\_AMOUNT |
| Treasury undelegation period | 28 days | DELEGATION\_UNBONDING\_PERIOD |
Notice expiry is not an unconditional withdrawal date. Liabilities and reservations can retain collateral beyond it, including through a long-lived asset's maturity. The treasury period does not apply to every self-funded operator withdrawal.
## Rewards [#rewards]
| Setting | Testnet value | Key |
| ----------------------------------- | ---------------- | ---------------------- |
| Annual reward-pool parameter | 25,000,000 ASSET | REWARD\_POOL\_ANNUAL |
| Epoch duration | **3 hours** | EPOCH\_LENGTH |
| Conditional role floor | 20% | ROLE\_FLOOR\_PCT |
| Minimum validators for a role floor | 3 | FLOOR\_MIN\_VALIDATORS |
| Minimum role notional for a floor | $5M | FLOOR\_MIN\_NOTIONAL |
The annual parameter is an allocation input, not proof of funded rewards or a yield promise. Finalization checks funding and eligibility. The source seed at revision `8a880c2` sets a **one-day [epoch](/docs/resources/glossary#epoch)**; the live testnet snapshot instead reports **10,800 seconds**. Other values listed above match the corresponding seed values.
## Oracle guards [#oracle-guards]
| Setting | Testnet value | Key |
| -------------------------------- | ------------- | -------------------- |
| Maximum price age | 7 days | MAX\_PRICE\_AGE |
| Maximum ordinary update step | 20% | MAX\_PRICE\_STEP |
| Minimum ordinary update interval | 1 hour | PRICE\_SET\_COOLDOWN |
These guards constrain the authorized setter. They do not verify the source price or guarantee an update schedule. Governance can force a price update through the timelock. See [price dependencies](/docs/business-validators/lifecycle#price-and-keeper-dependencies).
# Rewards (/docs/business-validators/rewards)
## Rewards come from a funded pool [#rewards-come-from-a-funded-pool]
The reward distributor allocates ASSET over [epochs](/docs/resources/glossary#epoch). It supports an emission-controller funding path and a prefunded mode. It does not mint an arbitrary amount when an operator requests payment.
Finalization checks that funds cover outstanding claims and the epoch's allocation. A calculated reward and a finalized, claimable reward are therefore different states.
## Allocation has two levels [#allocation-has-two-levels]
See [worked examples](/docs/business-validators/examples#one-reward-epoch) for the age, experience, and reputation formulas and a complete role/operator allocation. [Protocol parameters](/docs/business-validators/parameters#rewards) gives the verified testnet epoch duration and conditional floors.
First, the protocol allocates the pool across TV, SV, and IV roles. Role floors are subject to participation and [notional](/docs/resources/glossary#notional) activation conditions; they are not unconditional allocations to a single operator.
Within each role, validator weight reflects:
* **Stake:** the USD-equivalent collateral backing participation.
* **Age:** how long collateral has remained posted.
* **Experience:** the [BVID](/docs/resources/glossary#bvid)'s history of serving distinct assets.
* **Reputation:** its recent penalty record.
New deposits start with no tenure. Adding capital does not instantly give it the age of an older position.
## Eligibility changes the result [#eligibility-changes-the-result]
Health, BVID status, wind-down, overdue scoring evaluation, and provisional penalty freezes affect reward eligibility. Degraded health reduces the applicable weight; inactive or jailed participation does not receive ordinary active rewards. Voluntary wind-down has its own notice-period treatment.
Relevant inputs are snapshotted for the epoch. A deposit or treasury buy-out after the snapshot does not rewrite the already-open epoch's allocation.
## Treasury-backed accounts [#treasury-backed-accounts]
Where enabled, the account's reward is split between the operator and treasury using their age-weighted positions. Account-level eligibility checks apply before that split. Treasury funding does not create a second pool or exempt the account from a freeze.
See [Treasury delegation](/docs/business-validators/delegation) for ownership, buy-out, and exit behavior.
## Reading a reward balance [#reading-a-reward-balance]
Check the epoch, whether it has finalized, what has already been claimed, and which operator currently controls the BVID. Compare the dashboard with contract state before treating a displayed estimate as available funds.
There is no fixed yield implied by these mechanics. Allocation depends on funding, other participants, collateral, tenure, and eligibility. The numerical return examples in the engineering specification are model scenarios, not quoted returns for Real Testnet or a future production network.
# Validator roles (/docs/business-validators/roles)
## Three roles [#three-roles]
Each role owns a different part of the asset lifecycle. Open a role guide for its responsibilities, operating workflow, and limits.
| Role | Responsibility |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Tokenization Validator (TV)](/docs/business-validators/tokenization-validator) | Register and maintain the asset's protocol record |
| [Scoring Validator (SV)](/docs/business-validators/scoring) | Publish default probabilities and maintain their calibration |
| [Insurance Validator (IV)](/docs/business-validators/settlement) | Underwrite defined obligations and meet covered claims |
An organization can hold more than one role. Each requires its own authorization and collateral account.
## One identity, separate role accounts [#one-identity-separate-role-accounts]
A Business Validator identity, or **[BVID](/docs/resources/glossary#bvid)**, links an operator address to a legal-entity reference and registered roles. Experience and offence history are associated with the BVID; collateral is accounted for separately for each role.
The legal-entity reference is an identifier. The contract does not independently verify incorporation documents or detect every duplicate legal entity. Admission and identity review therefore remain part of the operating process.
| Permission | What it allows |
| -------------------------- | ------------------------------------------------------------------ |
| BVID operator | Authorized actions for the registered Business Validator roles |
| Token-suite owner or agent | Asset-contract actions assigned by that suite |
| Network validator | Participation in network consensus |
| Governance authority | Changes allowed by the protocol's governance and timelock controls |
Holding one of these permissions does not confer the others.
# Scoring Validator (/docs/business-validators/scoring)
## A probability, not a promise [#a-probability-not-a-promise]
A Scoring Validator (SV) publishes a probability of default for covered assets and keeps those predictions current. A prediction of 5% does not promise repayment; it says that default is expected to be uncommon across comparable observations. The protocol evaluates a collection of predictions rather than treating each default as misconduct.
The operator also declares a methodology commitment and reference. This makes methodology changes observable without making the contract an auditor of the underlying model.
## From predictions to outcomes [#from-predictions-to-outcomes]
1. The SV publishes and updates predictions for covered assets.
2. A [cohort](/docs/resources/glossary#cohort) closes, fixing the predictions used for that cohort.
3. The configured forward horizon and payment allowance elapse.
4. The contract evaluates eligible scheduled-payment outcomes.
The implemented outcome test reads whether relevant payments were resolved on time. It does not rely solely on when a [keeper](/docs/resources/glossary#keeper) happened to mark a payment missed. Assets with no scheduled payment in the horizon are excluded from the eligible sample.
The reference design uses a one-year forward horizon. The deployment's configured horizon, publication cadence, and evaluation deadlines govern actual operation; a cohort is not ready merely because its publication window has closed.
## What calibration measures [#what-calibration-measures]
The test uses a [Brier score](/docs/resources/glossary#brier-score): the average squared difference between a predicted probability and the observed binary outcome. Confident predictions that turn out wrong contribute more error.
The protocol compares observed error with the expected error implied by the predictions, allowing for sample size. Lower error is better, but perfect calibration does not require zero error. A minimum eligible sample is required; a skipped small sample is not a successful calibration result.
Evaluation can proceed in bounded chunks of on-chain computation, so a large cohort does not have to fit into a single transaction.
## Operational responsibilities [#operational-responsibilities]
Follow the [Brier example](/docs/business-validators/examples#one-brier-evaluation) to calculate an observed score, expected score, standard error, and breach threshold. The [parameter reference](/docs/business-validators/parameters#scoring-insurance-and-exit) records the verified horizon and minimum sample.
Keep predictions current, declare methodology changes through the supported process, and track when cohorts become evaluable. Overdue evaluation can restrict rewards and new volume; it is different from a completed evaluation with too few eligible observations.
A calibration breach enters the [penalty process](/docs/business-validators/mechanisms). Missed publication cadence and unannounced methodology changes have their own enforcement paths.
## Limits of the signal [#limits-of-the-signal]
Calibration depends on the protocol's settlement records and defined horizon. It does not independently assess every legal, liquidity, valuation, or operational risk of an instrument. The current exit model also does not retain an SV's collateral until every future cohort has been evaluated; a late evaluation is not a guarantee that collateral remains available to debit.
## Prepare scoring operations [#prepare-scoring-operations]
Follow [Become a Business Validator](/docs/business-validators/become-a-validator) for admission, role collateral, and monitoring preparation. A scoring role does not grant token-management authority or commit an insurer to cover the asset.
# Insurance Validator (/docs/business-validators/settlement)
## Responsibility [#responsibility]
An Insurance Validator (IV) underwrites specified asset obligations through policies with defined coverage, expiry, and a beneficiary. It must maintain the capital and operational process to meet covered claims.
Insurance capital and protocol stake serve different purposes. Claims are funded from the IV's business capital; ASSET stake makes failures costly. A posted stake balance does not establish that every insured loss can be paid.
## The payment schedule anchors the obligation [#the-payment-schedule-anchors-the-obligation]
An asset's schedule records amounts and due times. The settlement interface exposes whether each payment is missed or resolved. Insurance and scoring consume those records, so their meaning must remain consistent across integrations.
A partial payment does not resolve a full obligation. Resolution requires the recorded cumulative payment to reach the amount due.
## How the tokenization adapter records payment [#how-the-tokenization-adapter-records-payment]
The T-REX settlement adapter records payment attestations from an authorized settlement reporter. Each record includes a payment reference and evidence commitment. Timer-based missed-payment marking and eligible claim opening can be triggered by other callers, but payment recording is permissioned.
The adapter is an accounting bridge to the payment process. Calling it does not itself move fiat or stablecoins to investors. A payment recorded on-chain therefore carries a trust dependency on the reporter and its evidence process. Do not interpret it as independent proof of a bank transfer.
## From a shortfall to a claim [#from-a-shortfall-to-a-claim]
At testnet block 4503, one address held the settlement-reporter role. Governance can change that address through the [timelock](/docs/resources/glossary#timelock). The reporter's evidence and operational controls matter because scoring and insurance consume its records. A [keeper](/docs/resources/glossary#keeper) can trigger eligible time-based processing, but cannot replace a missing payment attestation with independent proof of payment.
An IV binds a policy to an asset with specified coverage, expiry, and a beneficiary. When a covered scheduled payment is missed, claim eligibility and size are derived from the policy and settlement records.
Coverage is bounded. The adapter accounts for the remaining shortfall and available policy coverage, rather than allowing every overlapping policy to claim the whole loss. When several policies cover a payment, claim-opening order can affect which policy's coverage is allocated first.
The tokenization adapter treats the policy beneficiary as a trustee or special-purpose entity representing holders. It does not automatically allocate the claim across every current token holder.
## Payout and enforcement [#payout-and-enforcement]
The IV is responsible for funding the claim from its operating capital. The reporter records claim payments, and full recorded payment resolves the claim. Late resolution and continued non-payment lead to different [penalty paths](/docs/business-validators/mechanisms).
A penalty against stake and payment of the insurance claim are separate events. Slashing does not by itself demonstrate that the beneficiary has received compensation.
## Recovery has its own limits [#recovery-has-its-own-limits]
The protocol includes interfaces for the [Disaster Recovery Fund (DRF)](/docs/resources/glossary#drf) and [NDT recovery claims](/docs/resources/glossary#ndt). They allow enforcement and wind-down to record recovery obligations and route proceeds.
These components currently have reference implementations; production funding and redemption remain unverified. Coverage, beneficiary rights, available recovery funds, and distribution arrangements must be confirmed for the particular deployment and instrument.
## Prepare insurance operations [#prepare-insurance-operations]
Follow [Become a Business Validator](/docs/business-validators/become-a-validator) for admission and role preparation. Plan for [insurance book transfer and wind-down](/docs/business-validators/wind-down#insurance-book-transfer) before accepting long-lived policies.
# Tokenization Validator (/docs/business-validators/tokenization-validator)
## Responsibility [#responsibility]
A Tokenization Validator (TV) registers the asset's [notional](/docs/resources/glossary#notional) value, metadata commitment, token linkage, and payment schedule in the Business Validator Protocol. It maintains this record as the instrument changes and re-attests information when required.
The work continues after issuance. Other participants use the record to identify the asset, assess its obligations, and interpret settlement outcomes. A hash proves which information was committed, not that the underlying information is true.
## Before onboarding an asset [#before-onboarding-an-asset]
Confirm that your [BVID](/docs/resources/glossary#bvid) holds the TV role and can accept new volume. Prepare the asset information, payment schedule, and token linkage required by the integration. Check that the protocol record describes the instrument the issuer actually operates.
TV status does not automatically grant ownership or administrative access to an issuer's token contracts. Those permissions belong to the [token suite's authority model](/docs/tokenization/token-suites). Deploying a token suite and registering its Business Validator responsibilities are separate steps.
## Maintain the record [#maintain-the-record]
Track material changes to the instrument and keep the metadata commitment current. Monitor registered material events, re-attestation deadlines, and changes to the linked contracts. An update to a document outside the protocol does not by itself update the on-chain record.
Stale information and unauthorized contract changes can trigger enforcement. An allegation that the record misrepresents the actual instrument requires evidence and a dispute. See [Penalties and disputes](/docs/business-validators/mechanisms) for how these paths resolve.
## Collateral follows responsibility [#collateral-follows-responsibility]
The asset's notional contributes to the TV role's collateral requirement. A penalty can affect collateral backing the role's wider portfolio, rather than only a separately ring-fenced amount for that asset.
An eligible replacement TV can take over a stale asset through fresh attestation and the applicable integration checks. Until liabilities are released, an asset becoming stale or orphaned does not automatically make the original TV's stake withdrawable. See [Exit and wind-down](/docs/business-validators/wind-down).
## Prepare asset operations [#prepare-asset-operations]
Follow [Become a Business Validator](/docs/business-validators/become-a-validator) for admission and operational preparation. For the issuer's asset-management workflow, use the separate [Tokenization Engine guide](/docs/tokenization/issuer-workflow).
# Exit and wind-down (/docs/business-validators/wind-down)
## Exit is an obligation process [#exit-is-an-obligation-process]
A Business Validator cannot discharge an asset book merely by disconnecting its wallet. Voluntary exit starts a notice period and blocks new business. Existing responsibilities continue while the protocol processes the portfolio.
Notice rules depend on the role. Insurance exit also considers the remaining policy term. A notice deadline is not a promise that every stake position becomes withdrawable on that date.
## Tokenization and scoring [#tokenization-and-scoring]
When TV service ends, assets can require fresh attestation from another eligible TV. SV service can lapse or be replaced. The token contracts do not disappear because a service provider exits.
The protocol distinguishes a service portfolio from a liability portfolio. An asset becoming stale or orphaned does not automatically remove its [notional](/docs/resources/glossary#notional) from the collateral requirement. Unresolved liabilities can remain through maturity, and stake requirements fall as the relevant obligations are actually released.
## Insurance book transfer [#insurance-book-transfer]
The IV reassignment process offers an existing policy book to eligible replacement insurers. It uses commit-reveal bidding, then checks whether a bid is financially feasible and the bidder can absorb the book. The lowest feasible premium is preferred; a failed candidate can fall through to another eligible bidder.
Policy processing and economic finalization can take multiple transactions. An auction being settled does not mean that every policy has already moved. Live claims must be handled against the applicable policy ownership during the transition.
If no feasible replacement is found, policies can be cancelled and recovery claims recorded through the [NDT](/docs/resources/glossary#ndt)/[DRF](/docs/resources/glossary#drf) interfaces. That is a loss of coverage, not guaranteed replacement insurance. See the [recovery limits](/docs/business-validators/settlement#recovery-has-its-own-limits).
## Forced exit [#forced-exit]
Severe insurance failures, upheld fraud, repeated offences, or authorized governance action can start forced wind-down without the ordinary voluntary notice. Enforcement and portfolio resolution still have separate states and consequences.
## Plan the exit before onboarding [#plan-the-exit-before-onboarding]
Long-lived assets can leave long-lived collateral obligations. Before accepting an asset, identify who can replace your service, how outstanding claims will be handled, and what releases its notional from the requirement. Check both [BVID](/docs/resources/glossary#bvid) status and the remaining liability portfolio; neither a finished notice period nor an empty service list is sufficient on its own.
# Network architecture (/docs/chain/architecture)
## An Avalanche L1 [#an-avalanche-l1]
Real Chain is an Avalanche Layer 1 with its own validator set and one EVM blockchain. Its architecture follows the standard Avalanche L1 model rather than introducing a new consensus protocol or virtual machine.
| Layer | Role in Real Chain |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| AvalancheGo | Runs the node, peer-to-peer networking, bootstrapping, block production, and consensus engine |
| Snowman consensus | Orders and accepts a linear sequence of blocks through repeated validator sampling |
| Subnet-EVM | Executes Ethereum transactions and maintains accounts, balances, contract code, logs, and storage |
| Validator Manager | Controls which nodes and weights form the L1 validator set |
| P-Chain | Records the L1 and its validators for Avalanche network coordination and interoperability |
Avalanche calls this a sovereign network because the L1 defines its own validator membership and token economics. REAL still uses the Avalanche Primary Network's P-Chain as the validator registry. Real Chain validators sync the P-Chain, but they do not participate in P-Chain consensus unless they separately validate the Primary Network. See Avalanche's [L1 overview](https://build.avax.network/docs/avalanche-l1s) and [network architecture](https://build.avax.network/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/03-network-architecture).
## Consensus and EVM execution [#consensus-and-evm-execution]
Snowman is Avalanche's consensus protocol for linear blockchains. Validators repeatedly sample other validators' preferences until a block reaches the configured confidence threshold. A vote for a block also supports its accepted ancestors, which lets the network converge on one ordered history. AvalancheGo runs this consensus process; Subnet-EVM verifies and executes the transactions inside each proposed block.
This separates two decisions:
1. **Is the block accepted?** Network Validators reach consensus on the ordered block history.
2. **Is the transaction valid?** Subnet-EVM applies account rules, gas rules, and contract code. A transaction that violates a contract check reverts even if its containing block is accepted.
The consensus parameters and validator weights determine how validator responses contribute to acceptance. They must be configured consistently across the network. For implementation detail, see Avalanche's [consensus architecture](https://build.avax.network/docs/nodes/architecture/consensus).
## Validator model: PoA today, PoS later [#validator-model-poa-today-pos-later]
Real Chain currently uses a permissioned Proof-of-Authority validator model. PoA governs admission to the validator set; it does not replace Snowman consensus. A `PoAManager`, whose owner was verified as the protocol [timelock](/docs/resources/glossary#timelock) at testnet block 4503 on 17 September 2026, initiates validator additions, removals, and weight changes. The P-Chain records the resulting validator set. The [trust model](/docs/resources/trust-model) identifies the observed timelock controls.
REAL's planned path is a governed migration to Proof of Stake using the network's native ASSET token. The migration hands Validator Manager control from the PoA manager to a native-token staking manager. After that transition, staking rules can govern new validator admission, weight, delegation, uptime-based rewards, and exits.
The PoS migration is a future network-governance action, not a currently active capability. It changes validator admission and incentives; it does not replace Subnet-EVM, change application contract state, or switch Real Chain away from Snowman consensus. Avalanche documents both models in its [Validator Manager architecture](https://build.avax.network/docs/avalanche-l1s/validator-manager/contract).
## Network validators [#network-validators]
Network Validators run AvalancheGo and participate in consensus. Joining the validator set requires admission through the active validator-management model; running node software by itself does not establish membership.
Operators maintain connectivity, synchronization, monitoring, software updates, and the credentials required by their role. Independent infrastructure and administration reduce common failure modes. Several nodes exposed to the same operational failure do not provide the same resilience as independently operated nodes.
Network Validators and Business Validators are separate roles. Network Validators secure block production and consensus. Business Validators perform assigned tokenization, scoring, or insurance responsibilities. One organization may perform both roles, but neither role automatically grants the other.
## Follow a transaction [#follow-a-transaction]
1. **Sign.** A wallet authorizes a transaction for the Real Chain ID, destination, value, and call data.
2. **Submit.** An RPC node validates the transaction format and places an acceptable transaction in its local transaction pool.
3. **Build and verify.** An eligible validator orders transactions into a candidate block. Subnet-EVM executes them, and other validators verify the resulting state transition.
4. **Reach consensus.** Validators use Snowman to decide whether to accept the block and its history.
5. **Confirm.** Once the block is accepted, a receipt records each included transaction's status, emitted logs, and gas used.
6. **Index.** Explorers and application indexers consume accepted blocks and logs to build searchable views.
A transaction hash proves submission, not acceptance or successful execution. Applications should wait for a receipt and check its status. A portal may remain behind the chain while its indexer processes the accepted block; that delay does not authorize submitting the transaction again.
## Chain state and application views [#chain-state-and-application-views]
Subnet-EVM stores the canonical on-chain state. This includes native ASSET balances, contract bytecode and storage, token balances, identity records, and Business Validator protocol records.
Indexers transform blocks and contract logs into query-oriented views for the explorer, portals, and APIs. Those services may also combine chain data with off-chain workflow state, such as document review or a pending bank payment. An indexed view can be stale or incomplete without changing the underlying chain state.
## Keep the control layers distinct [#keep-the-control-layers-distinct]
| Control | What it governs |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| Network governance | Validator admission, consensus configuration, node software, and coordinated network upgrades |
| Contract administration | Contract configuration, roles, and permitted upgrades |
| Application access | Sessions, workspace membership, and service actions |
| Asset eligibility | Which identities and transfers satisfy a token's configured rules |
A network operator does not gain issuer authority by running a node. An issuer administrator does not gain network-governance powers by operating an asset.
## Finality and external obligations [#finality-and-external-obligations]
An accepted Snowman block is intended to provide irreversible finality; Real Chain does not rely on a longest-chain confirmation race. Applications must still distinguish submission from acceptance and check the receipt's execution status. This documentation does not publish an independently measured REAL finality benchmark.
Finality concerns the blockchain record. A bank payment, document review, or service obligation has its own completion conditions. An application should show those conditions explicitly instead of treating every successful transaction as completion of the entire business workflow.
# Build an application (/docs/chain/build)
## What you will build [#what-you-will-build]
This example connects to Real Testnet, checks the chain ID, reads a listed permissioned token, checks recipient eligibility, and simulates an ordinary transfer. It uses no private key and sends no transaction.
Use **Node.js 24** and **viem 2.52.2**, the versions used for verification. In an empty project, run:
```sh
npm init -y
npm install viem@2.52.2
```
Save the following as `read-and-preflight.mjs`, or [download the example](/examples/read-and-preflight.mjs). The default sender and recipient are deliberately unprepared addresses so you can observe a refusal before using real test wallets.
## Read and simulate [#read-and-simulate]
```js
import {
BaseError, ContractFunctionRevertedError, createPublicClient,
defineChain, getAddress, http, parseAbi, parseUnits,
} from 'viem';
const response = await fetch('https://testnet.rwa-platform.real.finance/v1/config');
if (!response.ok) throw new Error(`Configuration request failed: ${response.status}`);
const config = await response.json();
if (config.chainId !== 117711) throw new Error('Unexpected configuration chain');
const chain = defineChain({
id: 117711, name: 'Real Testnet',
nativeCurrency: { name: 'ASSET', symbol: 'ASSET', decimals: 18 },
rpcUrls: { default: { http: [config.rpcUrl] } },
});
const client = createPublicClient({ chain, transport: http() });
if (await client.getChainId() !== chain.id) throw new Error('RPC chain mismatch');
// A listed test token; replace these public addresses for your own simulation.
const token = getAddress(process.argv[2] ?? '0xe157Af54109e7bc05ed868Cd859cc01908Fd1DdD');
const sender = getAddress(process.argv[3] ?? '0x0000000000000000000000000000000000000001');
const recipient = getAddress(process.argv[4] ?? '0x0000000000000000000000000000000000000002');
const blockNumber = await client.getBlockNumber();
if (!await client.getCode({ address: token, blockNumber })) throw new Error('No token code');
const tokenAbi = parseAbi([
'function name() view returns (string)',
'function decimals() view returns (uint8)',
'function balanceOf(address) view returns (uint256)',
'function identityRegistry() view returns (address)',
'function paused() view returns (bool)',
'function transfer(address,uint256) returns (bool)',
]);
const read = (functionName, args = []) => client.readContract({ address: token, abi: tokenAbi, functionName, args, blockNumber });
// Sequential reads also work with conservative public RPC rate limits.
const name = await read('name');
const decimals = await read('decimals');
const balance = await read('balanceOf', [sender]);
const paused = await read('paused');
const registry = await read('identityRegistry');
const recipientVerified = await client.readContract({
address: registry, abi: parseAbi(['function isVerified(address) view returns (bool)']),
functionName: 'isVerified', args: [recipient], blockNumber,
});
const amount = parseUnits(process.argv[5] ?? '1', decimals);
if (amount <= 0n) throw new Error('Use a positive transfer amount');
console.log({ chainId: chain.id, blockNumber: String(blockNumber), token, name, decimals,
senderBalance: String(balance), paused, recipientVerified });
try {
await client.simulateContract({ address: token, abi: tokenAbi, functionName: 'transfer',
args: [recipient, amount], account: sender, blockNumber });
console.log('Simulation succeeded. No transaction was sent.');
} catch (error) {
const revert = error instanceof BaseError
? error.walk(cause => cause instanceof ContractFunctionRevertedError) : undefined;
if (!(revert instanceof ContractFunctionRevertedError)) throw error;
console.log(`Simulation refused: ${revert.reason ?? revert.shortMessage}`);
console.log('No transaction was sent. Resolve balance, pause, freeze, identity, or compliance restrictions before retrying.');
}
```
Run it:
```sh
node read-and-preflight.mjs
```
To use your own token and wallets, pass public addresses and a positive human-readable token amount in this order:
```text
node read-and-preflight.mjs TOKEN SENDER RECIPIENT AMOUNT
```
The optional addresses select the simulated call; they do not grant signing authority. Reads and simulation use one block number so the result describes a consistent snapshot.
## Expected result [#expected-result]
On **17 September 2026**, block **4503**, the default example read **Acme M23 Bond**, 18 decimals, an unpaused token, a zero sender balance, and an unverified recipient. Simulation reverted with **Insufficient Balance**. That is the expected contract refusal, not a failed connection. Other errors, such as an unreachable RPC, are rethrown rather than disguised as transfer refusals.
For a permitted transfer, the sender needs enough unfrozen balance and the recipient must satisfy identity checks. Both wallets and the token must satisfy freeze, pause, and compliance rules. A successful simulation is evidence for that block only; recheck before asking a wallet to sign.
## Move from simulation to an application [#move-from-simulation-to-an-application]
Use the [contract reference](/docs/resources/testnet-contracts) and [network configuration](/docs/chain/networks) for the selected environment. Keep native ASSET available for transaction gas when you later introduce wallet-signed transactions.
Show awaiting signature, submitted, confirmed, and indexed states separately. A transaction hash is not a success receipt, and the indexer may update later. Never retry a submission just because the portfolio has not refreshed.
The [platform integration guide](/docs/tokenization/integration) explains session-based [preflight](/docs/resources/glossary#preflight) and durable jobs. Platform preflight can impose additional account checks beyond this direct contract simulation.
# Real Chain (/docs/chain)
## The network is part of the product [#the-network-is-part-of-the-product]
Real Chain is REAL's dedicated Avalanche Layer 1, built with Subnet-EVM. It provides the execution environment for asset contracts and the shared on-chain record used by applications and services.
Financial assets need continuing operations: eligibility changes, transfers, payments, reporting, and servicing. A dedicated network lets REAL govern the infrastructure supporting that work, including validator participation, execution capacity, fees, and network upgrades.
## Why REAL uses a dedicated network [#why-real-uses-a-dedicated-network]
EVM compatibility is the baseline, not the differentiator. REAL operates a dedicated network so that infrastructure policy can follow the needs of its financial system rather than the priorities of an unrelated general-purpose chain.
| REAL controls | Effect on the system |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Validator participation | Network admission can follow REAL's governance model for qualified operators |
| Blockspace and execution policy | Financial applications do not compete directly with activity on an unrelated chain |
| Fees and native gas | REAL can set network-level fee policy, while keeping gas costs distinct from asset payments and protocol service fees |
| Network upgrades | Changes to the chain can be governed and coordinated for REAL's own application stack |
| Canonical financial state | Token contracts and Business Validator records can share one authoritative transaction history |
These controls do not collapse the system's roles. Network Validators secure consensus. Asset contracts define holder eligibility and transfer rules. Business Validators remain accountable for the information and services they provide.
## Start here [#start-here]
* Read [network architecture](/docs/chain/architecture) to understand how transactions become application state.
* Use [networks and connectivity](/docs/chain/networks) to connect to the verified testnet.
* Follow [Build an application](/docs/chain/build) to plan a development workflow.
For the wider design rationale, see REAL's [Why REAL Runs Its Own Chain](https://medium.com/@RealFinOfficial/why-real-runs-its-own-chain-646a80f1fdc7).
# Networks and connectivity (/docs/chain/networks)
## REAL Testnet [#real-testnet]
Use the testnet to validate integrations before relying on them in a production environment. The RPC below responded with EVM chain ID **117711** on **16 September 2026**.
| Setting | Value |
| ---------------- | ----------------------------------------------------------------------- |
| Network name | Real Testnet |
| EVM chain ID | 117711 |
| Native gas token | ASSET |
| Block explorer | [testnet.explorer.real.finance](https://testnet.explorer.real.finance/) |
| Faucet | [testnet.faucet.real.finance](https://testnet.faucet.real.finance/) |
**RPC URL**
[https://testnet.rpc.real.finance/ext/bc/F9iT4dEEByJ4hCn76XtgEqu3UwEEL1PA25ZCkWSn6TMR1div9/rpc](https://testnet.rpc.real.finance/ext/bc/F9iT4dEEByJ4hCn76XtgEqu3UwEEL1PA25ZCkWSn6TMR1div9/rpc)
## Connect a wallet or application [#connect-a-wallet-or-application]
Follow [Add Real Testnet to your wallet](/docs/chain/wallet-setup) for MetaMask, Rabby, or Core. Applications use the chain ID, full RPC URL, and native token above. Confirm the selected chain before signing. Obtain test ASSET from the faucet when a wallet needs gas, and use the explorer to inspect submitted transactions.
The RPC path includes an Avalanche blockchain ID. That identifier selects the blockchain served by the node; the numeric EVM chain ID identifies the network when signing transactions. They are different values and cannot be substituted for one another.
## Gas and transaction fees [#gas-and-transaction-fees]
### Faucet limits [#faucet-limits]
The public faucet configuration on **17 September 2026** reported **1 ASSET per successful request**, a rolling **24-hour** window, **one request per address**, and **three per IP**. A CAPTCHA is required. The dispenser is prefunded and can run out; an available web page is not a guarantee of a successful request. These are test tokens for gas and testing.
Real Testnet uses native **ASSET** to pay for transaction execution. Asset tokens and payment stablecoins do not provide the native balance required for gas. Request test ASSET from the [faucet](https://testnet.faucet.real.finance) and keep enough in the submitting wallet for every transaction in the workflow.
Gas cost depends on the operation and current network fee conditions. Estimate the actual transaction against Real Testnet before submitting it. A permissioned transfer can execute identity and compliance checks, so its gas use can differ from a simple native-token transfer. A reverted transaction can still consume gas.
Network fees are separate from asset purchase amounts and application service fees. A multi-step workflow may also require separate approval and execution transactions. Fetch current fee data rather than treating a configured network parameter as a permanent price.
## What RPC access provides [#what-rpc-access-provides]
The public gateway exposes Ethereum-compatible JSON-RPC calls used to read chain state and submit signed transactions. The gateway configuration restricts administrative APIs and applies request limits. Do not assume a public endpoint exposes every method available on a private node.
The chain RPC gateway does not expose its corresponding Ethereum WebSocket path. Use HTTP for chain RPC calls. The separate live API WebSocket is listed under developer endpoints below.
## Access is separate from authority [#access-is-separate-from-authority]
Public RPC access lets an application read state and submit signed transactions. Contract administration requires the relevant role, and receiving a permissioned token requires its identity and compliance checks. These are separate from connecting to the network.
Testnet tokens support testing. Testnet addresses, balances, and deployment state must not be treated as production configuration. A separate verified configuration is required for another environment.
## Testnet services [#testnet-services]
| Service | Use it for |
| ------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Dashboard](https://testnet.dashboard.real.finance) | View the network and protocol dashboard; some functions may require access |
| [Block explorer](https://testnet.explorer.real.finance) | Inspect addresses, blocks, contracts, and transactions |
| [Faucet](https://testnet.faucet.real.finance) | Request test ASSET for gas |
| [Investor portal](https://testnet.rwa.real.finance) | Follow investor verification, access, and asset workflows |
| [Issuer portal](https://testnet.tokenize.real.finance) | Manage an issuer workspace and its assets |
## Developer endpoints [#developer-endpoints]
These are service entry points. Authentication, supported operations, and response formats depend on the service; publishing a link does not imply anonymous access to every operation.
| Endpoint | Purpose |
| ----------------------------------------------------------------------------------- | -------------------------------------- |
| [REST API](https://testnet.api.real.finance/v1) | Network and protocol application API |
| [Network metadata](https://testnet.api.real.finance/v1/meta) | Discover metadata exposed by the API |
| [Blockscout API](https://testnet.explorer.real.finance/api) | Explorer API entry point |
| [Tokenization API](https://testnet.rwa-platform.real.finance) | Tokenization platform service |
| [Tokenization readiness](https://testnet.rwa-platform.real.finance/v1/health/ready) | Check platform readiness |
| [Tokenization indexer health](https://testnet.rwa-ponder.real.finance/health) | Check the tokenization indexer service |
**Live API WebSocket:** wss\://testnet.api.real.finance/v1/ws
This is the application API's live-update connection, not an Ethereum JSON-RPC WebSocket endpoint. Do not configure it as a wallet RPC or assume it accepts Ethereum subscription methods.
# Add Real Testnet to your wallet (/docs/chain/wallet-setup)
## Before you start [#before-you-start]
Have your wallet installed and unlocked. Use the [Real Testnet network settings](/docs/chain/networks#real-testnet): network name **Real Testnet**, chain ID **117711**, and native currency symbol **ASSET**. Copy the complete RPC URL, including its blockchain-specific path, and the explorer URL from that page.
Adding a network configures a connection. It does not move funds, create an investor identity, or grant access to a permissioned asset. You do not need to provide a recovery phrase or private key to add these settings.
## MetaMask [#metamask]
### Browser extension [#browser-extension]
1. Open the menu and choose **Networks**.
2. Select **Add a custom network**.
3. Enter the network name, RPC URL, chain ID, currency symbol, and block explorer URL from the network settings.
4. Save the network and select **Real Testnet** in the network selector.
### Mobile [#mobile]
Open the network selector from the Tokens tab, switch to **Custom**, and choose **Add a custom network**. Enter the same settings, save, and select Real Testnet.
Menu placement can vary by release. See MetaMask's official [add-network instructions](https://support.metamask.io/configure/networks/how-to-add-a-custom-network-rpc).
## Rabby [#rabby]
### Browser extension [#browser-extension-1]
1. Open Rabby's settings or **More** menu and find the custom-network/testnet settings.
2. Choose the option to add a network.
3. Enter the Real Testnet RPC URL and check that the detected chain ID is **117711**. Complete the name, currency symbol, and explorer fields with the supplied settings.
4. Save the network. When connecting to a REAL testnet application, confirm that the connection or transaction request uses this custom network.
Custom network settings are separate from replacing the RPC for a network Rabby already supports. Rabby's extension implements this flow in its [custom-network screen](https://github.com/RabbyHub/Rabby/tree/develop/src/ui/views/CustomTestnet). These instructions cover the extension; they do not assume an identical mobile interface.
## Core [#core]
### Browser extension [#browser-extension-2]
1. Open **Settings**, then **Networks**.
2. Select the **+** button to add a custom network.
3. Enter the Real Testnet RPC details and the other network settings.
4. Select **Save**. Check that Real Testnet is the active network.
Follow Core's official [custom-network instructions](https://support.core.app/en/articles/6425528-core-extension-how-do-i-add-custom-networks) if your interface differs. This procedure covers Core extension.
## Check the connection [#check-the-connection]
Open the [testnet faucet](https://testnet.faucet.real.finance) to request test ASSET for transaction fees. Use the same wallet address you intend to transact from. After the faucet transaction completes, inspect the address in the [block explorer](https://testnet.explorer.real.finance).
For asset workflows, continue to the [investor portal](https://testnet.rwa.real.finance) or [issuer portal](https://testnet.tokenize.real.finance). Connecting a wallet is the first step; each portal has its own account and authorization flow.
## If the network will not connect [#if-the-network-will-not-connect]
* **Chain ID mismatch:** use the complete Real Testnet RPC URL and decimal chain ID 117711. Do not substitute Avalanche C-Chain settings.
* **Network already exists:** inspect the existing entry and correct its RPC rather than adding conflicting copies.
* **Zero native balance:** confirm the selected network and wallet address, then check the faucet transaction in the explorer.
* **An asset token is missing:** adding the network does not automatically import every token or establish issuer admission. Check the asset wallet and token address in the portal or explorer.
# Documentation status (/docs/resources/documentation-status)
## Available in this edition [#available-in-this-edition]
* Network, asset, and Business Validator explanations with separate authority boundaries.
* Investor powers and recovery, issuer workflows, identity, offerings, and secondary-market responsibilities.
* [Trust model](/docs/resources/trust-model) and [security review status](/docs/resources/security-and-audits), including audit-evidence limits.
* [Testnet contracts](/docs/resources/testnet-contracts) and [BV parameters](/docs/business-validators/parameters), verified at chain 117711, block 4503, on **17 September 2026**.
* Public platform configuration and faucet limits checked on the same date. API observations are service snapshots rather than block-pinned records.
* A [runnable viem quickstart](/docs/chain/build): token reads, recipient eligibility, expected refusal, and successful simulation were exercised without sending transactions.
* Four worked examples, four diagrams with native text, reader paths, and an expanded glossary.
* Search, page Markdown, and full Markdown exports.
## How to interpret evidence [#how-to-interpret-evidence]
**Implementation behavior** explains the checked contract or service version. **Repository defaults** are starting settings, not automatically deployed values. **Verified testnet configuration** states a date and, for contract reads, a block. **Planned capability** remains separate from available functionality.
The checked protocol revision is 8a880c2; tokenization is b6c0906. Later uncommitted distribution work was excluded. Source review and simulation do not substitute for independent audits or production release assessment.
## Pending verification and publication [#pending-verification-and-publication]
* Current production network selection, controller arrangements, connectivity, and release evidence.
* Public independent audit reports and confirmation that their scope matches deployed implementations.
* Public BV admission contact, criteria, and an end-to-end registration guide.
* Production recovery-fund funding and NDT redemption behavior.
* Complete authenticated API/ABI references, recovery walkthroughs, and portal/Scribe recordings.
* Verified production fees, KYB requirements, retention policy, and legal statements suitable for public use.
* Distribution, redemption, and corporate-action workflows.
Testnet migration tools for internal testing and Ethereum staking are outside this pass. Test tokens and illustrative calculations do not represent a production financial offer.
## Markdown and AI access [#markdown-and-ai-access]
Use [the documentation index](/llms.txt) or [the full Markdown collection](/llms-full.txt). Diagrams retain readable step text. An on-site AI assistant is not enabled.
# Glossary (/docs/resources/glossary)
## ASSET [#asset]
Native currency used for gas and BV collateral on Real Testnet. It is separate from permissioned asset tokens.
## Agent [#agent]
An address authorized to perform specified contract operations, such as minting or identity registration.
## Brier score [#brier-score]
Mean squared error between predicted probabilities and binary outcomes. The protocol compares it with an expected score and threshold.
## Business Validator [#business-validator]
Participant assigned tokenization, scoring, or insurance responsibilities backed by protocol stake.
## BVID [#bvid]
On-chain identifier for a Business Validator; distinct from its current operator wallet.
## Claim [#claim]
Signed attestation about an identity, such as completion of an eligibility check.
## Claim issuer [#claim-issuer]
An entity or contract that issues attestations. It may differ from the asset token issuer.
## Cohort [#cohort]
A collection of predictions fixed for evaluation over a defined outcome horizon.
## Compliance module [#compliance-module]
Contract that applies a configured rule to a proposed token operation.
## DRF [#drf]
Disaster Recovery Fund: protocol recovery interfaces and reference implementation for receiving and routing recovery proceeds; the name does not establish available funding.
## EOA [#eoa]
Externally owned account: an address controlled directly by a private key rather than by wallet-contract code.
## Epoch [#epoch]
A reward accounting interval with snapshotted inputs and a separate finalization step.
## Escrow [#escrow]
Contract that holds payment funds and releases or refunds them according to its rules.
## Forced transfer [#forced-transfer]
A privileged agent operation that moves holdings without a holder signature, subject to its specific contract checks.
## Freeze [#freeze]
Restriction on a wallet or an amount of its tokens; distinct from pausing all ordinary transfers.
## Health [#health]
The protocol assessment of collateral coverage. Other status or eligibility restrictions can still apply.
## Identity registry [#identity-registry]
Suite contract associating wallets with ONCHAINIDs and evaluating required claims.
## Insurance Validator [#insurance-validator]
IV: a Business Validator underwriting specified obligations; insurance operating capital is separate from protocol stake.
## Issuer [#issuer]
Organization issuing an asset token and responsible for its associated terms and operations.
## IV [#iv]
Abbreviation for Insurance Validator.
## Keeper [#keeper]
Service that submits eligible maintenance transactions. It has only the permissions assigned to its address.
## KYC and KYB [#kyc-and-kyb]
Know Your Customer and Know Your Business: verification processes for people and organizations; implementation scope and legal requirements are separate questions.
## Management key [#management-key]
An ONCHAINID key with identity-management authority; it is not necessarily controlled by the asset wallet holder.
## NAV [#nav]
Net asset value used to price a fund subscription at acceptance under the offering rules.
## NDT [#ndt]
The protocol recovery-claim instrument associated with DRF interfaces. Reference accounting does not guarantee redemption or a funded payout.
## Network validator [#network-validator]
Node operator participating in chain consensus, separate from Business Validator and issuer roles.
## Notional [#notional]
Principal or face value under a role’s responsibility, rather than the sum of future interest payments.
## ONCHAINID [#onchainid]
Identity contract containing keys and claims; wallets can be associated with it through a suite identity registry.
## Oracle [#oracle]
Authorized input mechanism for an external value, such as ASSET/USD. Its data source and update controls determine the trust dependency.
## Pause [#pause]
Token control that stops ordinary transfers; privileged operations can have different checks.
## Preflight [#preflight]
Preliminary evaluation of a proposed operation. Its result does not reserve balance or future eligibility.
## Provisional penalty [#provisional-penalty]
An assessed penalty with reservations and immediate restrictions, before final debit or reversal.
## Proxy [#proxy]
Contract forwarding execution to an implementation; the relevant upgrade authority may change that implementation.
## RPC [#rpc]
Remote procedure call interface used to read chain state or submit signed transactions.
## Safe [#safe]
A smart-contract wallet whose configured owners and threshold authorize execution.
## Scoring Validator [#scoring-validator]
SV: a Business Validator publishing and maintaining probability-of-default predictions.
## SIWE [#siwe]
Sign-In with Ethereum: wallet-message authentication used to establish a platform session.
## Stake [#stake]
Collateral posted to support protocol accountability; posted balance and withdrawable balance can differ.
## SV [#sv]
Abbreviation for Scoring Validator.
## Timelock [#timelock]
Contract requiring scheduled privileged operations to wait a minimum delay before authorized execution.
## Token suite [#token-suite]
Permissioned token plus its identity, trusted-issuer, claim-topic, and compliance contracts.
## Tokenization Validator [#tokenization-validator]
TV: a Business Validator responsible for assigned asset onboarding and maintenance duties.
## Treasury delegation [#treasury-delegation]
Restricted treasury funding of BV stake, with ownership and withdrawal rules; not public retail delegation.
## TV [#tv]
Abbreviation for Tokenization Validator.
## WAD [#wad]
Fixed-point scale of 10 to the power 18, used for protocol ratios and USD values.
## Wind-down [#wind-down]
Process for ending assignments while resolving or retaining outstanding obligations.
# Resources (/docs/resources)
Controllers, upgrade rights, and effects on users.
Review evidence and its scope.
Verified addresses and dated control observations.
Terms used across the three systems.
What this edition covers and what remains to verify.
# Security and audits (/docs/resources/security-and-audits)
## Read audit status by component and version [#read-audit-status-by-component-and-version]
This documentation was checked against implementation sources. That review is not an independent security audit. A feature running on testnet also does not establish production audit clearance.
Status checked on **17 September 2026**:
| Component | Available evidence | Coverage limit |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Business Validator protocol | The reviewed release-gap register lists an independent audit as an open mainnet requirement | No completed independent audit report was verified for revision `8a880c2` or its testnet deployment |
| JurisdictionModule | Project records report an external audit completed and remediated on 3 July 2026, with remediation commit `1f656e7` | The external report is held by platform operations; a public report and match to the deployed implementation were not verified |
| EscrowedOffering and SecondaryMarket | Specifications describe a combined external audit/release gate | Completion and coverage of current deployments were not verified; testnet feature flags are not audit evidence |
| AssetMetadataRegistry and IssuerRegistry | Implementation source was reviewed | Independent audit coverage was not verified |
| Upstream T-REX and ONCHAINID | Dependencies provide token and identity contracts | This edition does not verify upstream audit coverage for every deployed version and integration |
“Not verified” means available evidence did not establish the claim. It does not assert that no review has ever taken place.
## Assess a release [#assess-a-release]
An applicable audit identifies the revision, contracts, exclusions, findings, remediation, and subsequent changes. A module audit does not cover later upgrades, the entire platform, or an asset's legal and operational risks.
Read [Trust model and admin powers](/docs/resources/trust-model) alongside this page. Upgrades, identity administration, external payment records, and price inputs remain relevant even for audited code.
Testnet supports integration testing with test assets. Production deployment and operational readiness require separate evidence. Remaining documentation gaps are maintained on [Documentation status](/docs/resources/documentation-status).
# Testnet contract reference (/docs/resources/testnet-contracts)
## Verified snapshot [#verified-snapshot]
Chain **117711**, block **4503**, checked **17 September 2026**. These addresses were discovered through the public platform configuration and network metadata, then checked for contract code at that block. Proxy implementation slots were read where applicable. This verifies observed deployment state, not full source-bytecode equivalence or audit coverage.
ASSET is native gas currency and has no ERC-20 token address on Real Testnet. The example asset token below is a separate permissioned test instrument.
## Contracts [#contracts]
| Contract | Address | Purpose |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| GovernanceParams | [0x7c6bCAD6651fF3ae8fFBaF1dea075D0b3092bA73](https://testnet.explorer.real.finance/address/0x7c6bCAD6651fF3ae8fFBaF1dea075D0b3092bA73) | Read economic settings and authorized roles |
| ProtocolTimelock | [0xe8FCDAA57e43256106A226f4C7061B37b9938ebB](https://testnet.explorer.real.finance/address/0xe8FCDAA57e43256106A226f4C7061B37b9938ebB) | Read governance delay and roles |
| PriceOracle | [0x4dB54A525aC8c3aeee8F1E8d02120142795878e8](https://testnet.explorer.real.finance/address/0x4dB54A525aC8c3aeee8F1E8d02120142795878e8) | Read ASSET/USD valuation and freshness |
| StakeVault | [0x1611C3EAdd635E4cCf6495E837DDDc6Dd5359AE2](https://testnet.explorer.real.finance/address/0x1611C3EAdd635E4cCf6495E837DDDc6Dd5359AE2) | Read BV collateral positions |
| BVIDRegistry | [0x22deC618553609176967fe70C905C43f92100009](https://testnet.explorer.real.finance/address/0x22deC618553609176967fe70C905C43f92100009) | Read BV identities and status |
| RewardDistributor | [0x3aE63d259a2bc56c4C6cC2F7791023089f1D994c](https://testnet.explorer.real.finance/address/0x3aE63d259a2bc56c4C6cC2F7791023089f1D994c) | Read epoch and reward state |
| TrexSettlement | [0x656103Be522391E30B4bdd7b723c6bB201eF3e80](https://testnet.explorer.real.finance/address/0x656103Be522391E30B4bdd7b723c6bB201eF3e80) | Read reported payment outcomes |
| T-REX factory | [0x08f9F823c3737Ea5F341dE11330b5E914115482c](https://testnet.explorer.real.finance/address/0x08f9F823c3737Ea5F341dE11330b5E914115482c) | Identify suite deployment infrastructure |
| JurisdictionModule | [0x374fD59A14f2B42F44acc601520a01213d2a5e0d](https://testnet.explorer.real.finance/address/0x374fD59A14f2B42F44acc601520a01213d2a5e0d) | Shared jurisdiction checks |
| SecondaryMarket | [0x27BD6EaD3A3a4d1a9f483EB7928c0AC6Cb63c21D](https://testnet.explorer.real.finance/address/0x27BD6EaD3A3a4d1a9f483EB7928c0AC6Cb63c21D) | Signed-quote settlement |
| Acme M23 Bond (test fixture) | [0xe157Af54109e7bc05ed868Cd859cc01908Fd1DdD](https://testnet.explorer.real.finance/address/0xe157Af54109e7bc05ed868Cd859cc01908Fd1DdD) | Token used by the developer quickstart |
## Observed implementations [#observed-implementations]
Call the proxy address above for ordinary reads. These are the implementation addresses observed behind the EIP-1967 proxies, not alternative user entry points.
| Proxy | Implementation |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| GovernanceParams | [0x4b4fd522480f2c5f244b72b67ca243bb5c06bd52](https://testnet.explorer.real.finance/address/0x4b4fd522480f2c5f244b72b67ca243bb5c06bd52) |
| PriceOracle | [0x70a010aa5aba8b6e16e83fb6f76a301a92ca8e46](https://testnet.explorer.real.finance/address/0x70a010aa5aba8b6e16e83fb6f76a301a92ca8e46) |
| StakeVault | [0xb1532cf7e2ef660828b38fc2cd634d943ce54524](https://testnet.explorer.real.finance/address/0xb1532cf7e2ef660828b38fc2cd634d943ce54524) |
| BVIDRegistry | [0xafdbb5cd9eb3d3aae42347d8673845173c577ff7](https://testnet.explorer.real.finance/address/0xafdbb5cd9eb3d3aae42347d8673845173c577ff7) |
| RewardDistributor | [0x30617533c213b309c511a5c52d3e016fc995aa5e](https://testnet.explorer.real.finance/address/0x30617533c213b309c511a5c52d3e016fc995aa5e) |
| TrexSettlement | [0x96eef460c0dd7ac55bfd501c36a453f640e2421c](https://testnet.explorer.real.finance/address/0x96eef460c0dd7ac55bfd501c36a453f640e2421c) |
| JurisdictionModule | [0x8f16eb507552bffccb8c4f290175066f59ffaf1a](https://testnet.explorer.real.finance/address/0x8f16eb507552bffccb8c4f290175066f59ffaf1a) |
T-REX token suites use an implementation-authority pattern. An empty EIP-1967 slot on the example token does **not** make that token immutable.
## Observed authorities [#observed-authorities]
| Control | Observation |
| ---------------------------------------------------- | -------------------------------------------------------- |
| GovernanceParams administrator and PoA manager owner | ProtocolTimelock |
| Timelock minimum delay | 1 hour |
| Proposer, executor, and canceller | Same address: 0x02b77D8e7d2533A1c025b4D1F623c68eA703a78f |
| Price setter | 0x872a87B5B95ea16216879749D827444AEb40940f |
| Settlement reporter | 0x02b77D8e7d2533A1c025b4D1F623c68eA703a78f |
| T-REX authority and JurisdictionModule owner | 0xa1C581dAf8a7FF9fEe9Ba27ae3ef66D75014e779 |
[Timelock](/docs/resources/glossary#timelock) role-grant events were reconciled against current role membership at the snapshot block. The single proposer/executor observation is not evidence of distributed governance. [Trust model and admin powers](/docs/resources/trust-model) explains the consequences.
## Refresh before integration [#refresh-before-integration]
Use [configuration discovery](/docs/tokenization/integration#discover-testnet-configuration) and [network metadata](https://testnet.api.real.finance/v1/meta) to discover the intended environment, then verify code, roles, and implementations on its RPC. A feature flag or code-bearing address does not establish an audited release.
[Build an application](/docs/chain/build) uses the listed test fixture for read-only calls and a transfer simulation.
# Trust model and admin powers (/docs/resources/trust-model)
## Separate authorities [#separate-authorities]
Network validators order transactions. Business Validators perform asset-related services. Issuers control their token suites, while platform administrators manage shared infrastructure and identity services. Holding one role does not confer the others.
The tables describe implementation powers. Dated [testnet observations](/docs/resources/testnet-contracts) identify controls independently read on-chain. Technical power is separate from legal authority to exercise it.
## Network and Business Validator protocol [#network-and-business-validator-protocol]
| Controller | Power and effect | Approval mechanism |
| ---------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Network-management owner | Changes permissioned network-validator participation through management contracts | Owner-authorized transactions; separate from BV admission |
| Protocol timelock | Upgrades UUPS protocol contracts and administers the governance parameter store | A proposer schedules an operation; an authorized executor executes it after the minimum delay |
| Governance parameter administrator | Changes economic parameters and address roles, including price and settlement reporters | When held by the timelock, changes pass through its scheduling and execution process |
| Authorized price setter | Updates ASSET/USD collateral valuation | Direct signed updates subject to step, cooldown, and freeze checks |
| Protocol timelock | Forces a price update or freezes the oracle | Timelocked action; a forced update can bypass ordinary step/cooldown guards |
| Settlement reporter | Records asset and insurance payments used by scoring and enforcement | Permissioned attestation; the adapter records evidence rather than transferring payment |
The [timelock](/docs/resources/glossary#timelock) delays privileged changes; its presence alone does not establish decentralized governance. Proposer and executor roles determine who can initiate and complete changes. See [protocol parameters](/docs/business-validators/parameters) for economic settings.
## Tokenization and identity [#tokenization-and-identity]
| Controller | Power and effect | Approval mechanism |
| ------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Issuer token owner | Appoints token agents and transfers ownership | Owner transaction; a Safe requires its configured approvals |
| Token agent | Mints, burns, freezes, pauses, force-transfers, and performs supported recovery | Agent transaction; holder consent is not required for these privileged actions |
| Issuer identity-registry agent | Registers or removes wallet-to-identity associations for its suite | Agent transaction; removal affects eligibility, not the recorded balance |
| Issuer compliance owner | Configures supported suite compliance rules | Owner transaction through the compliance interfaces |
| Platform registry owner | Controls required topics and trusted claim issuers | Owner transaction; requirements can affect existing holders immediately |
| Platform identity-management key | Manages platform-provisioned investor ONCHAINIDs and adds claims | MANAGEMENT-key authority; an asset wallet is not automatically its identity's management key |
| Claim issuer and key administrator | Issues/revokes attestations and rotates signing authority | Retiring a signing key can invalidate claims still using it |
| T-REX implementation authority owner | Changes implementations used by suites following that authority | Owner-controlled version management; no built-in BV protocol timelock |
| Shared JurisdictionModule owner | Upgrades the shared jurisdiction implementation | Owner-authorized UUPS upgrade; no built-in BV protocol timelock |
| Market owner and quote signer | Rotates the quote signer; co-signs fill plans and fees | Owner transaction for rotation; quote signatures for settlement |
Standard suite deployment hands token, identity-registry, and modular-compliance ownership to the issuer. The platform retains the trusted-issuer and claim-topic registries. Those registry powers are separate from a token-agent role.
EscrowedOffering, SecondaryMarket, AssetMetadataRegistry, and IssuerRegistry are non-proxy contracts in the reviewed implementation. They still have privileged operational controls. Immutable code does not remove operator, registry, or quote-signing dependencies.
## What to check [#what-to-check]
* **Investors:** read [issuer powers and recovery](/docs/tokenization/investor-workflow#issuer-powers-and-holder-risks) alongside the instrument's terms.
* **Issuers:** account for shared upgrades and identity dependencies even when your wallet owns the token.
* **Business Validators:** model changes in collateral prices, governance parameters, and reporter inputs.
* **Integrators:** verify roles and implementations for the selected deployment; configuration discovery does not certify security.
## Evidence and production status [#evidence-and-production-status]
At testnet block **4503**, read on **17 September 2026**, GovernanceParams and the PoA manager were controlled by the protocol timelock. Its minimum delay was **one hour**. The same single address held proposer, executor, and canceller roles. The T-REX authority and shared JurisdictionModule had the same platform-owner address. These observations do not establish independent multisignature control.
Implementation review: protocol `8a880c2` and tokenization `b6c0906`, checked on 17 September 2026. The [contract reference](/docs/resources/testnet-contracts) records live testnet observations.
Production controller assignments, multisignature arrangements, and network selection remain unconfirmed in this edition. Historical plans are not presented as current commitments. See [Security and audits](/docs/resources/security-and-audits) for review coverage.
# Asset information and documents (/docs/tokenization/asset-information)
## The asset record [#the-asset-record]
A token's balances are only one part of an asset's information. The platform associates the token with its issuer, asset classification, collateral classification, jurisdiction, descriptive metadata, and supporting documents.
Asset and collateral classifications describe different things. An instrument's type describes what the investor holds; collateral describes what, if anything, supports the obligation. A classification is descriptive data, not a guarantee of asset quality or protection.
## Files and on-chain records [#files-and-on-chain-records]
Rich descriptions and files are stored outside the token contract. The supported publication flow validates metadata, pins content to IPFS, and prepares the on-chain write for the authorized issuer wallet.
On-chain records associate the token with metadata locations and document hashes. A hash lets a reader check whether the downloaded file matches the recorded version. It does not prove that the statements inside the file are true.
## Public information and private evidence [#public-information-and-private-evidence]
Public asset material can include the description, logo, offering terms, and published reports. Identity documents and private subscription evidence serve different purposes and should not be added to the public document set.
Subscription-specific signed agreements and payment evidence belong to their dedicated workflow. They are not interchangeable with a publicly published agreement template.
## Updating and listing an asset [#updating-and-listing-an-asset]
An update requires the appropriate issuer or contract authority. Preparing or uploading a file does not complete the change: the associated on-chain write must succeed, and the indexer must observe it before all views reflect the update.
A new suite is initially unlisted in the public asset directory. Listing is a separate platform-controlled step; deployment or publication of metadata alone does not grant it. An unlisted token may still support authorized operations, so directory visibility should not be used as a proxy for its contract state.
# Identity and eligibility (/docs/tokenization/identity)
## Wallets and identities [#wallets-and-identities]
A wallet is the address an investor uses to hold tokens and submit transactions. An [ONCHAINID](/docs/resources/glossary#onchainid) is an identity contract that holds keys and claims. A suite's identity registry associates the investor's wallet with that identity.
These serve different purposes: the wallet participates in transactions, while the identity supplies attestations that a suite can evaluate. Registering a wallet is one step in eligibility, not an automatic approval for every asset.
## Claims and trust [#claims-and-trust]
A claim is an attestation from a claim issuer about a particular topic. For example, a claim may attest that an investor has completed an identity check. The claim issuer is the party making that attestation; it is not necessarily the issuer of the asset token.
Each suite defines two things:
* **Required topics:** the kinds of claim an investor must have.
* **Trusted issuers:** the claim issuers accepted for those topics.
A claim can exist on an identity without being accepted by a particular token. Trust determines whether it counts; it does not make the claim private or invisible on-chain.
## Reuse does not mean universal access [#reuse-does-not-mean-universal-access]
Suppose an investor uses the same identity for two assets. Both suites can accept a platform-issued claim if their trust settings allow it. A claim from an asset-specific issuer may count for one suite and be ignored by the other.
Reusing the identity avoids treating each asset as an entirely separate identity record. Each suite still evaluates its own requirements, and its wallet registration and transfer rules still apply.
## Identity eligibility and transfer permission [#identity-eligibility-and-transfer-permission]
Issuer admission is an additional step: the issuer registers the wallet and identity in its suite. The platform verification path prepares reusable claims, but it does not automatically register the investor into every asset.
Issuers may also attest to investors they have verified themselves. Those attestations use the issuer's own claim authority and are accepted only where trusted. This path does not imply that the platform performed the underlying verification or ongoing screening.
There are two separate questions:
| Question | What is evaluated |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Does the identity meet this suite's requirements? | Wallet registration and valid claims from issuers trusted for the required topics |
| Is this particular transfer permitted? | Applicable compliance rules and token conditions, such as pauses, freezes, and available balance |
Passing the first check does not guarantee the second. An investor can satisfy the required identity checks while a proposed transfer fails a geographic restriction or an operational control.
These checks enforce the rules configured in the contracts. They do not establish complete legal compliance or independently verify all facts about an investor or asset.
## Ordinary transfer flow [#ordinary-transfer-flow]
1. **Token state:** ordinary transfers must be unpaused; the sender and recipient must be unfrozen, and enough unfrozen balance must be available.
2. **Recipient identity:** the recipient must be registered and have valid claims from accepted issuers for every required topic.
3. **Compliance:** configured modules evaluate the proposed transfer, including applicable jurisdiction and holding limits.
4. **Outcome:** if every check passes, balances and compliance accounting update atomically. Any failed check reverts the transfer.
This flow describes ordinary transfers. Privileged [token operations](/docs/tokenization/operations) use their own checks; the platform [preflight](/docs/resources/glossary#preflight) may impose additional account restrictions.
## Jurisdiction in REAL [#jurisdiction-in-real]
REAL models jurisdiction as a claim so that its acceptance follows the suite's trust settings. The jurisdiction compliance module reads a trusted, valid claim and checks its country value against the suite's configured geographic rules.
The underlying identity storage also has a country field. That field is distinct from the trusted claim used by REAL's jurisdiction module; changing the field alone is not the same as changing the accepted jurisdiction claim.
In the platform suite configuration, the issuer's trusted jurisdiction claim takes priority where present and valid; the platform claim provides the fallback. A different suite does not accept that issuer's claim merely because it shares the investor's identity.
## Custom claims [#custom-claims]
An issuer can define organization-specific topics and issue claims through the platform's signing service. Some topics represent a yes-or-no attestation; others carry a typed value.
Requiring a custom topic checks for an accepted, valid claim. Storing a value in that claim does not automatically create a transfer rule that evaluates the value. Value-based enforcement needs a corresponding compliance module, as with jurisdiction.
## Required topics and signing-key changes [#required-topics-and-signing-key-changes]
The standard suite starts with KYC, AML, SANCTIONS\_CLEARED, and JURISDICTION requirements. The platform treats this default set as a non-removable baseline in issuer-facing topic management. Adding another required topic can immediately make existing holders who lack it ineligible to receive tokens.
The reviewed claim-validation path does not provide automatic on-chain expiry. Revocation, trusted-issuer configuration, and signing-key validity determine acceptance. Before retiring a claim-signing key, the responsible operator must reissue affected claims with their original verified meaning; otherwise existing claims can become invalid.
An issuer's own accepted claims can satisfy its suite without the investor taking the platform-provider verification route for that suite. This does not confer platform-wide verification or eligibility for other issuers.
## Eligibility can change [#eligibility-can-change]
Eligibility is evaluated against current claims and configuration. Revocation, loss of claim validity, changes to trusted issuers, or changes to required topics can affect the result. Transfer permission can also change when compliance rules or token controls change.
A failed eligibility check does not automatically remove tokens already held. Transfers and authorized asset-management operations remain governed by their respective contract rules.
When a transfer is refused, first distinguish an identity problem from a transfer restriction. Check registration and accepted claims, then the applicable rules and token state. A platform's preliminary check can explain a likely refusal; the executed transaction determines the on-chain outcome.
# Tokenization Engine (/docs/tokenization)
## From an asset to an operating token [#from-an-asset-to-an-operating-token]
The Tokenization Engine brings together asset contracts, investor identity, issuer tools, and transaction workflows. It supports the work that continues after a token is created: admitting investors, maintaining asset information, applying transfer controls, and recording operations.
Each issuer can operate multiple token suites. A suite uses ERC-3643 through the T-REX contracts to connect token balances with identity and compliance checks. Investor identities can be reused, while each suite retains its own admission and eligibility requirements.
## What the engine provides [#what-the-engine-provides]
| Area | Purpose |
| ----------------- | ----------------------------------------------------------------------------- |
| Asset tokens | Deploy a suite and configure its token and operating roles |
| Investor access | Combine reusable identity claims with issuer-controlled admission |
| Asset information | Associate a token with its issuer, classification, metadata, and documents |
| Operations | Support issuance, transfers, freezes, recovery, and other authorized actions |
| Offerings | Coordinate subscriptions, agreements, payments, and delivery |
| Secondary trading | Support signed sell orders and on-chain settlement where enabled |
| Integration | Connect portals and applications to platform workflows and indexed chain data |
## Who controls what? [#who-controls-what]
The issuer controls admission to its assets and performs authorized token operations. Organization membership governs access to the issuer workspace; contract permissions govern what a wallet can execute on-chain.
The platform coordinates identity verification, claims, deployment jobs, and supporting services. In the platform deployment model, the issuer receives ownership of the token, identity registry, and modular compliance contracts. Required-topic and trusted-issuer registry authority remains with the platform.
Investors hold asset tokens in their designated wallets. Personal wallets and existing [Safe](/docs/resources/glossary#safe) multisignature wallets have different approval flows. A platform session does not replace a wallet signature or the approvals required by a Safe.
## Choose a reading path [#choose-a-reading-path]
* **Issuers:** follow the [issuer workflow](/docs/tokenization/issuer-workflow) from workspace setup to ongoing operations.
* **Investors:** follow the [investor workflow](/docs/tokenization/investor-workflow) from identity verification to holding and transferring tokens.
* **Integrators:** use the [integration overview](/docs/tokenization/integration) to understand service boundaries and transaction state.
## Scope and availability [#scope-and-availability]
Self-service issuer onboarding is testnet-specific. Deployment, public directory listing, and market activation are separate decisions. Start with the [tested developer guide](/docs/chain/build), [configuration reference](/docs/tokenization/integration#discover-testnet-configuration), or [trust model](/docs/resources/trust-model). Remaining coverage gaps are listed in [Documentation status](/docs/resources/documentation-status).
# Integration overview (/docs/tokenization/integration)
## Three kinds of interaction [#three-kinds-of-interaction]
Applications work with the platform API, indexed chain data, and wallet-signed transactions. Each serves a different purpose; treating all three as a single synchronous operation can produce misleading status displays.
| Layer | Responsibility |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Platform services | Sessions, organization access, verification workflows, claims orchestration, and durable jobs |
| Indexer and read services | Searchable projections of balances, transfers, identities, claims, and asset records |
| Contracts and wallets | Enforce on-chain permissions and rules, authorize transactions, and record execution |
## Authentication and authority [#authentication-and-authority]
The portals use [Sign-In with Ethereum](/docs/resources/glossary#siwe) to establish wallet-associated sessions. Workspace membership controls platform actions, while contract roles control on-chain actions. Existing [Safe](/docs/resources/glossary#safe) accounts introduce threshold approvals and scoped owner or delegate access.
An application should show which account and wallet are acting, and distinguish preparing an operation from authorizing it. A valid session is not blanket transaction authority.
## Transaction and job state [#transaction-and-job-state]
Some platform operations create durable jobs, such as issuer registration, claims issuance, or suite deployment. Others ask an issuer or investor wallet to sign directly. Safe actions may wait for multiple approvals before execution.
Present the relevant stages explicitly: requested, awaiting authorization, submitted, confirmed, and reflected in indexed data. A queued job is not a confirmed transaction. A transaction receipt also does not guarantee that an indexed portfolio has already refreshed.
Reusing an existing request or its supported retry path is preferable to blindly creating a duplicate. Some failures require operator recovery, especially when the outcome of a submitted transaction is uncertain.
## Read models and preliminary checks [#read-models-and-preliminary-checks]
The platform normally reads chain-derived data through its indexer. This makes queries efficient but introduces a delay between execution and display. Integrations should communicate freshness and pending updates.
Transfer [preflight](/docs/resources/glossary#preflight) explains likely refusals using current information. The contracts remain authoritative when the transaction executes. A successful preliminary check cannot guarantee that balances, claims, or rules remain unchanged until submission.
## Environment boundaries [#environment-boundaries]
Resolve network and contract configuration for the intended environment. Token addresses, available market features, onboarding policy, and payment assets are deployment-specific. Testnet self-service access does not imply production admission or Business Validator permission.
## Discover testnet configuration [#discover-testnet-configuration]
The portal platform exposes public configuration at:
```text
GET https://testnet.rwa-platform.real.finance/v1/config
```
It returned HTTP 200 without authentication on **17 September 2026**. Relevant fields from that observation:
```json
{
"network": "testnet",
"chainId": 117711,
"features": {
"escrowDvpEnabled": true,
"secondaryMarketEnabled": true,
"issuerOnboardingEnabled": true,
"automaticTokenDeployment": true
},
"navStalenessDays": 1
}
```
This is an excerpt. The response also includes `rpcUrl`, `explorerUrl`, contract `addresses`, and claim `topics`. Feature flags describe the responding service; they do not prove every asset supports a feature or that a production audit gate has been met.
## Read and authenticate at the right service [#read-and-authenticate-at-the-right-service]
| Request | Access | Result |
| ------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
| `GET /v1/config` | Public | Deployment configuration and feature flags |
| `GET /v1/assets?limit=1` | Public, rate-limited | Listed assets in `data`, with `pagination` and freshness `meta` |
| `GET /v1/assets/:token` | Public, rate-limited | One listed asset and its documents |
| `GET /v1/portfolio` | Wallet session | Account-scoped positions and freshness information |
| `POST /v1/transfers/preflight` | Wallet session and CSRF protection | Preliminary transfer checks; no transfer submission |
These routes belong to `testnet.rwa-platform.real.finance`. They are not interchangeable with the network/protocol API at `testnet.api.real.finance/v1` or separate indexer APIs. Do not send an API key and assume it establishes a portal wallet session. The portal authentication flow uses Sign-In with Ethereum, scoped sessions, and CSRF protection for mutations.
Handle HTTP failures before parsing success data. Protected routes can reject missing sessions or insufficient permissions; rate limits can return 429. An unlisted or unknown asset can return 404. Preserve returned application error codes, such as `nav_stale`, rather than treating every 409 as a reason to repeat an action.
Use [Build an application](/docs/chain/build) for a complete viem read and contract simulation. The contract simulation is distinct from the account-scoped platform preflight above.
## Testnet services [#testnet-services]
The [tokenization API](https://testnet.rwa-platform.real.finance) provides the platform entry point. Check [API readiness](https://testnet.rwa-platform.real.finance/v1/health/ready) and [indexer health](https://testnet.rwa-ponder.real.finance/health) separately: a responsive API does not by itself prove its indexed view is current. The [network endpoint directory](/docs/chain/networks#developer-endpoints) also lists chain and protocol services.
# Investor workflow (/docs/tokenization/investor-workflow)
## Choose the wallet that will hold your assets [#choose-the-wallet-that-will-hold-your-assets]
The platform account is associated with one designated asset wallet. The documented flows support personal wallets and existing [Safe](/docs/resources/glossary#safe) multisignature wallets. Safe owners and delegates can have different session permissions; an owner signing in does not automatically satisfy every threshold approval.
Signing in uses a wallet message. It establishes a platform session and does not itself transfer assets or authorize every future transaction. On-chain actions require their own wallet approval and network gas.
## Establish identity and claims [#establish-identity-and-claims]
The platform verification path collects identity evidence through its verification provider. Successful processing prepares an [ONCHAINID](/docs/resources/glossary#onchainid) and the relevant claims. A submitted check, an approved provider result, and confirmed on-chain claims are different stages.
Identity documents belong in the verification process, not in public asset metadata. Claims and wallet associations are visible on-chain and can reveal attributes; they should not be described as anonymous merely because they omit a person's name.
## Request access to an asset [#request-access-to-an-asset]
A reusable identity does not grant access to every token. Each issuer decides whom to admit, and each suite evaluates its configured claims and rules.
An access request progresses through issuer review and on-chain registration. Only after the required registration and eligibility checks are satisfied can the wallet receive the token through the ordinary supported flows. See [identity and eligibility](/docs/tokenization/identity) for the distinction between accepted claims and permission for a particular transfer.
## Subscribe or acquire tokens [#subscribe-or-acquire-tokens]
Where an offering is available, the subscription process records the requested allocation, agreements, issuer acceptance, payment, and delivery. Submitting a subscription does not mean tokens have been delivered. Asset admission must be complete by delivery.
Where secondary trading is enabled, an eligible investor can buy from another holder's sell order. This remains subject to the token's rules at settlement; a displayed quote does not guarantee that a later transaction will succeed.
## Hold, transfer, and monitor [#hold-transfer-and-monitor]
The portfolio presents balances and activity associated with the asset wallet, including frozen amounts where applicable. A transfer [preflight](/docs/resources/glossary#preflight) can explain likely refusals before signing, such as a paused token, insufficient unfrozen balance, missing registration, or a jurisdiction restriction.
A successful preliminary check is not a reservation of eligibility or balance. Wait for the transaction result, then allow indexed views to catch up. Safe transactions additionally require the configured threshold of approvals and on-chain execution.
## When verification changes [#when-verification-changes]
Claims can be revoked or become invalid. Ordinary T-REX transfers check the recipient's identity eligibility alongside token and compliance restrictions. The platform's transfer preflight also checks the sender's eligibility. A portal refusal therefore need not mean the contract applies an identical sender check. Other compliance rules can still restrict either party.
Losing eligibility does not erase a balance. It can prevent receipt or block supported platform workflows until the responsible issuer or verification process resolves the issue.
## Issuer powers and holder risks [#issuer-powers-and-holder-risks]
Authorized token agents can freeze a wallet or amount, force-transfer holdings, and burn tokens without the holder signing those actions. Forced transfers and burns have privileged execution paths that remain available during an ordinary-transfer pause. An identity-registry agent can remove a wallet's registration for that suite; this changes eligibility rather than deleting the balance.
These powers can support recovery and enforcement, but also expose holders to errors or misuse by authorized operators. Wallet custody alone does not remove them. See [Trust model and admin powers](/docs/resources/trust-model).
## Identity control and wallet recovery [#identity-control-and-wallet-recovery]
The platform provisions investor ONCHAINIDs with its MANAGEMENT key. Holding the asset wallet's private key does not give the investor sole control of that identity. Claim updates and identity administration depend on the authorized management and claim-issuer keys.
The platform binds the asset wallet during onboarding; it has no ordinary self-service wallet-change flow in the reviewed version. Contract-level token recovery can transfer holdings to an approved replacement wallet, but it requires issuer-agent action and the identity requirements to be satisfied. Platform account and identity records also need coordination. This is an assisted recovery process, not a private-key reset.
## Rights attached to an asset [#rights-attached-to-an-asset]
The offering terms and issuer documents define payment, redemption, and enforcement rights. A token balance alone does not establish an insolvency priority or guarantee redemption. Check the instrument's payment schedule, responsible entity, and recovery arrangements before subscribing. Automated distributions and redemption are not established by the workflows described here.
## Try the testnet portal [#try-the-testnet-portal]
Open the [testnet investor portal](https://testnet.rwa.real.finance). First-time wallet users can follow [Add Real Testnet to your wallet](/docs/chain/wallet-setup).
# Issuer workflow (/docs/tokenization/issuer-workflow)
## 1. Establish the issuer workspace [#1-establish-the-issuer-workspace]
Prepare a personal wallet for testnet self-service, enough native ASSET for wallet-signed actions, the asset terms, and the intended owner and investor rules. Self-service requires a full-authority session with the personal wallet acting for itself. Existing [Safe](/docs/resources/glossary#safe) workflows are separate; a Safe or delegate session does not qualify for this personal-wallet onboarding path.
The source policy defaults to **one workspace per account** and **five suite deployments per issuer**. The deployment quota is configurable and was not read from a live administrative interface. Production KYB, admission requirements, fees, and service timelines remain unconfirmed; testnet registration does not settle them.
An issuer workspace represents the organization operating its token suites. It has a primary wallet and members with administrator, operator, or viewer permissions. Workspace permissions and on-chain ownership are separate: the wallet executing an operation must also hold the required contract role.
The platform supports operator-reviewed issuer onboarding and a separately enabled testnet self-service path. The self-service path is for eligible personal-wallet accounts; it does not create a Safe, grant Business Validator admission, or replace production admission requirements.
Issuer registration must finish before automatic token deployment can begin. If registration is pending, creating another workspace or repeating the deployment request is not a substitute for completing it.
## 2. Define the token and its rules [#2-define-the-token-and-its-rules]
New standard suites require **KYC, AML, SANCTIONS\_CLEARED, and JURISDICTION** claims. The issuer-facing platform preserves that baseline. Check existing investors before adding another required topic: the change can immediately affect their eligibility. See [identity and eligibility](/docs/tokenization/identity).
Prepare the token name, symbol, precision, and the asset it represents. Decide which investor requirements and supported compliance controls the suite needs, such as jurisdiction restrictions, a supply cap, or a maximum holding per wallet.
The [token suite](/docs/tokenization/token-suites) connects these settings to the contracts that enforce them. The asset's terms and supporting agreements remain the basis for the rights represented by the token.
## 3. Deploy and confirm control [#3-deploy-and-confirm-control]
In the operator-reviewed path, a suite request proceeds through approval before deployment. Where testnet automatic deployment is enabled, a registered issuer can submit a request within the environment's limits.
Deployment is a multi-step process. It creates the suite, configures the requested modules and roles, and hands the relevant ownership to the issuer wallet. Wait for the process to complete before treating the suite as ready.
New tokens start paused. Deployment does not admit investors, mint a supply, unpause transfers, or list the asset publicly.
## 4. Prepare the asset information [#4-prepare-the-asset-information]
Create the asset description, classification, jurisdiction information, and public document set. Review the information before authorizing its on-chain association with the token.
[Asset information and documents](/docs/tokenization/asset-information) explains how stored files and on-chain records work together. Public directory listing is a separate platform decision.
## 5. Admit eligible investors [#5-admit-eligible-investors]
Investors can request access after establishing platform eligibility. The issuer reviews each request and authorizes registration in the suite's identity registry. Approval in a workflow is not complete admission until the required on-chain registration succeeds.
An issuer can also introduce investors it has independently verified. That path uses the issuer's own claim authority and leaves verification and ongoing screening responsibility with the issuer. It must not be described as platform verification.
## 6. Begin and maintain operations [#6-begin-and-maintain-operations]
Issue tokens only to recipients who meet the suite's requirements. Review the configuration and operational readiness before unpausing ordinary transfers. Maintain documents, investor access, and token controls as the asset changes.
If the asset uses an offering, its subscription, payment, and delivery process is a separate workflow. A deployed token alone does not constitute an open offering. Safe-controlled issuers must allow time for the required co-signatures and execution.
## Open the testnet workspace [#open-the-testnet-workspace]
For primary issuance, continue with [offerings and subscriptions](/docs/tokenization/offerings). Check the payment window, agreement requirements, selected payment asset, and fee terms before opening an offering. A token deployment does not configure distributions, redemption, or corporate actions by itself; those workflows are not verified in this edition.
Use the [testnet issuer portal](https://testnet.tokenize.real.finance) to explore the available workflow. If your wallet is not configured, first [add Real Testnet](/docs/chain/wallet-setup).
# Offerings and subscriptions (/docs/tokenization/offerings)
## What an offering adds [#what-an-offering-adds]
An offering organizes the process of acquiring tokens from an issuer. It connects an allocation to an investor, the required agreement, payment instructions, and delivery. It is separate from creating the token suite.
Offerings support fixed-price issuance and fund subscriptions priced at [net asset value (NAV)](/docs/resources/glossary#nav). Fixed-price offerings use a subscription window and soft/hard caps. NAV subscriptions are open-ended, without a subscription window or soft-cap close test; an optional hard cap can limit reservations. The issuer publishes the NAV used to strike units at acceptance. Fund redemption is outside this subscription flow.
## The subscription journey [#the-subscription-journey]
1. The investor requests an allocation or subscription amount.
2. The required agreement and supporting documents are collected.
3. The issuer reviews and accepts or rejects the subscription.
4. The investor follows the selected payment instructions.
5. Payment is confirmed through the applicable rail.
6. Where a signed agreement is required, the issuer supplies the countersigned agreement before settlement.
7. Tokens are delivered to the investor's admitted, eligible wallet.
Platform eligibility can allow a subscription to begin, but suite admission is required by delivery. An allocation, payment, and delivered balance are separate states.
## Offering progression [#offering-progression]
1. **Draft → open:** the issuer sets terms, payment mode, and capacity before opening.
2. **Open ⇄ filled:** subscriptions reserve capacity; eligible releases can reopen room. Each subscription still needs acceptance and any required agreement.
3. **Close decision:** a fixed-price offering succeeds or fails its soft-cap test. Cancellation or suspension can interrupt progress; open-ended NAV offerings follow their own mode.
4. **Payment and delivery:** accepted subscriptions complete payment, required countersigning, and delivery. Failed or cancelled paid subscriptions follow the applicable refund path.
## Payment modes [#payment-modes]
Fixed-price reservations are first come, first served. Released reservations can reopen capacity while the subscription window remains open. The implementation's default payment window is **seven days**; use the offering's actual terms for the deadline. Each crypto offering selects **one** supported stablecoin. These are application rules, separate from gas fees.
The configured NAV staleness threshold was **one day** on testnet on 17 September 2026; the source default is **30 days**. A stale NAV requires explicit issuer confirmation in the supported acceptance flow. Read `navStalenessDays` from [configuration discovery](/docs/tokenization/integration#discover-testnet-configuration), rather than assuming the default applies.
| Mode | How payment is recorded |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| Bank transfer | The investor pays the issuer outside the chain; the issuer matches the reference and confirms receipt |
| Stablecoin | The investor makes an authorized deposit into the offering's escrow contract, where enabled |
| Mixed | Both rails are offered while allocations share the offering's capacity |
Uploading bank-payment evidence does not verify receipt. The issuer performs that confirmation. A direct stablecoin transfer to an arbitrary address is not a substitute for the authorized escrow deposit: payment must be associated with the accepted subscription.
The escrow holds the payment asset. The security token is delivered directly to the investor's asset wallet, rather than being held by the escrow as an intermediate token holder.
## Completion, cancellation, and refunds [#completion-cancellation-and-refunds]
Subscription windows, payment deadlines, funding targets, and issuer decisions affect whether an offering completes. A failed or cancelled allocation can enter a refund process if payment has already occurred. Bank refunds remain outside the chain; escrow refunds follow the contract's permitted states and conditions.
A recorded refund requirement is not the same as a completed refund. The applicable payment record and transaction result establish which stage has been reached.
An escrow's refund escape depends on its configured settlement window and offering mode: windowed offerings use their effective close, while rolling offerings use the individual deposit time. Read the deployed escrow terms; “14 days after payment” is not a universal rule.
## Example: subscribe for 100 bond tokens [#example-subscribe-for-100-bond-tokens]
Assume a fixed price of **$100 per token**, an open offering with sufficient capacity, a required agreement, a seven-day payment window, and bank-transfer settlement. These are example terms, not an available investment.
1. An investor requests **100 tokens**, reserving an allocation priced at **$10,000**.
2. The investor supplies the signed agreement; the issuer accepts the subscription. The investor follows its actual payment deadline and reference instructions.
3. The investor pays $10,000 by bank transfer. An uploaded receipt is supporting evidence; the issuer must confirm receipt.
4. The issuer supplies the countersigned agreement and completes suite admission before delivery. Any required offering-close condition must also be satisfied.
5. The authorized delivery transaction puts 100 tokens in the investor's eligible wallet. The platform then waits for confirmation and indexed display.
If the offering fails or the accepted subscription is cancelled after payment, the subscription enters the refund process. A refund status alone does not prove money has returned to the investor. Platform fees, if applicable, follow the offering terms; wallet-signed transactions additionally need ASSET gas.
## Fee terms [#fee-terms]
The launch design specifies zero primary and secondary platform fees, but current fee configuration was not independently read for this edition. Review the offering's fee terms and the signed secondary-market quote. The platform can change its runtime secondary fee policy; a historical launch value is not a permanent fee commitment. Gas is paid separately in ASSET.
## Testnet availability [#testnet-availability]
Public configuration reported stablecoin settlement enabled on 17 September 2026. Read the current [feature flags](/docs/tokenization/integration#discover-testnet-configuration) and the offering terms before using a payment rail. [Security and audits](/docs/resources/security-and-audits) records the separate audit-evidence limits.
# Token operations (/docs/tokenization/operations)
## Authority before action [#authority-before-action]
The connected wallet must hold the contract role required for the operation. A workspace administrator may be allowed to prepare an action without having the wallet authority to execute it. A [Safe](/docs/resources/glossary#safe)-controlled action follows its proposal, co-signature, and execution process.
## Operating controls [#operating-controls]
| Operation | Purpose |
| ---------------------------- | -------------------------------------------------------------------------- |
| Mint | Create tokens for a recipient, subject to the operation's checks |
| Burn | Remove tokens through an authorized supply operation |
| Pause or unpause | Control whether ordinary transfers can proceed |
| Freeze a wallet or an amount | Restrict movement of holdings covered by that control |
| Forced transfer | Move tokens using an authorized agent operation |
| Recovery | Move holdings to an approved replacement wallet under the recovery process |
| Manage agents | Assign or remove the relevant contract's operational permissions |
| Configure compliance | Update supported rules such as supply, holding, and jurisdiction limits |
Privileged operations do not necessarily follow the same checks as ordinary investor transfers. A pause or freeze should not be presented as disabling every possible administrative operation.
## Recovery is an authorized process [#recovery-is-an-authorized-process]
The token contracts support recovery involving a replacement wallet and identity checks. This is distinct from restoring a wallet's private key. In the T-REX implementation, recovery moves holdings through a [forced transfer](/docs/resources/glossary#forced-transfer); it does not burn the old balance and mint an equivalent new one.
The ability to perform recovery belongs to authorized agents and depends on the contract's requirements. It should not be described as a user-controlled password reset.
## Review, sign, confirm [#review-sign-confirm]
Review the intended recipient, amount, rule change, or role assignment before signing. [Preflight](/docs/resources/glossary#preflight) checks can expose a likely refusal, but another transaction or configuration change can alter the outcome before execution.
A submitted request, a collected Safe signature, and a confirmed transaction are different stages. Verify the final result before repeating an operation. If the transaction is confirmed but a portal still shows old data, account for indexing delay before assuming the operation failed.
# Secondary trading (/docs/tokenization/secondary-trading)
## A market between holders [#a-market-between-holders]
The secondary-market model lets holders offer tokens for sale to other eligible investors in the same suite. Sellers sign orders; the platform maintains the order book and prepares quotes; the settlement contract executes the exchange.
The documented version supports sell orders that buyers fill. Buy-side bids and a fiat payment leg are outside that version's scope. Secondary trading is also separate from redeeming fund units with an issuer.
## From listing to settlement [#from-listing-to-settlement]
1. The seller prepares an order defining the asset, quantity, price, and supported payment token.
2. The asset wallet signs the order. A [Safe](/docs/resources/glossary#safe) collects its required signatures before listing.
3. A buyer requests a quote against available orders.
4. The buyer reviews allowances and authorizes the settlement transaction.
5. The settlement contract checks signatures, the platform-signed quote, cancellation, expiry, fill accounting, and buyer limits. The token applies its transfer rules before fills complete.
Minimum fill sizes, [notional](/docs/resources/glossary#notional) floors, and order caps are platform quote-service policies. They are not all independently rechecked by the settlement contract. Settlement requires the platform's co-signature, so the quote signer is a trust and availability dependency. The signed quote also carries the applicable seller fee.
An order displayed in the book is not a guarantee that it remains fillable. Balances, allowances, eligibility, order expiry, and cancellation state can change.
## What moves on-chain? [#what-moves-on-chain]
Settlement couples the payment and asset transfer in an on-chain transaction. Asset tokens move from the seller to the buyer; payment moves from the buyer to the seller and any configured fee recipient. The market contract does not hold an inventory of investor asset tokens between trades.
The token still applies its own transfer checks. Listing on a market does not remove issuer admission requirements or compliance restrictions.
## Delisting and cancellation [#delisting-and-cancellation]
Removing a listing from the platform's book affects discovery and new quotes. A previously issued quote can remain valid within its commitment window. On-chain cancellation is the mechanism that invalidates the order at the contract level, subject to transaction ordering.
The platform is needed to obtain new listings and quotes. The contract provides an on-chain cancellation path independent of that service. Sellers should understand the difference before assuming a delisted order can no longer settle.
## Issuers as sellers [#issuers-as-sellers]
An issuer selling treasury tokens must also satisfy the holder requirements for its own suite. Issuer self-admission is a distinct action; owning the token contract does not automatically register the treasury as an eligible holder. The platform identifies issuer-owned orders so buyers can recognize that counterparty.
## Market availability [#market-availability]
Public configuration reported secondary trading enabled on testnet on 17 September 2026. Availability for a particular asset still depends on its rules, active orders, and the quote service. An enabled market does not guarantee liquidity. See [Security and audits](/docs/resources/security-and-audits) for review coverage.
# Token suites (/docs/tokenization/token-suites)
## What is a token suite? [#what-is-a-token-suite]
A token suite is the group of contracts behind a permissioned asset token. REAL's Tokenization Engine uses the T-REX implementation of ERC-3643 to connect token balances with identity checks and configurable transfer rules.
The token represents the asset according to its terms. The surrounding contracts determine which identities the suite recognizes, which attestations it accepts, and which additional rules apply to operations.
## The parts of a suite [#the-parts-of-a-suite]
| Component | Responsibility |
| ------------------------- | ---------------------------------------------------------------------- |
| Token | Records balances and handles transfers and authorized token operations |
| Identity Registry | Associates wallets with identities and checks the required claims |
| Identity Registry Storage | Stores wallet-to-identity associations and a country field |
| Claim Topics Registry | Defines which kinds of claim the suite requires |
| Trusted Issuers Registry | Defines which claim issuers are accepted for each kind of claim |
| Modular Compliance | Applies additional configured rules to token operations |
The storage contract's country field is part of the underlying suite structure. REAL's jurisdiction rules use trusted jurisdiction claims; the field alone does not determine geographic eligibility.
## How the parts work together [#how-the-parts-work-together]
For an ordinary transfer, the token checks its own operational conditions and consults the identity and compliance contracts. The recipient must satisfy the suite's identity requirements, and the proposed transfer must pass the applicable rules. A valid identity alone is not enough to approve every transfer.
For example, an investor may have the required identity claims but still be unable to receive an asset because the suite's geographic restrictions exclude their jurisdiction.
## Ownership and operation [#ownership-and-operation]
Contract owners and agents have different responsibilities. Ownership generally controls configuration and role assignment where supported by the contract. Agents perform the operations their roles allow, such as registering identities or minting, burning, and freezing tokens.
A role on one contract does not imply the same role on every contract in the suite. Access to an issuer workspace also does not, by itself, establish on-chain authority.
In the platform's deployment flow, the issuer wallet receives ownership of the token, identity registry, and modular compliance contracts and is assigned token and identity-registry agent roles. The platform retains authority over the required-topic and trusted-issuer registries. This is the platform's ownership model, rather than a universal requirement of ERC-3643.
Privileged operations have their own permission checks and can follow different rules from ordinary investor transfers. Asset operators should understand who holds those powers and what the asset's terms permit.
## What is shared across assets? [#what-is-shared-across-assets]
An investor can reuse an [ONCHAINID](/docs/resources/glossary#onchainid) identity across suites. Acceptance remains specific to each suite: its required claim topics and trusted issuers determine which claims count.
This allows shared identity infrastructure while preserving distinct asset rules. Two tokens can recognize the same investor identity and still reach different eligibility decisions.