> For the complete documentation index, see [llms.txt](https://docs.rwa-chain.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rwa-chain.io/architecture.md). # Architecture ## Layers ``` Ethereum L1 ── settlement & data availability │ ├── Base (OP Stack L2) ── where $RWAINC and the current ecosystem live today │ └── RWA Inc. Chain (OP Stack L2) ── this repo ├── op-geth execution ├── op-node consensus / derivation ├── op-batcher posts L2 batches to L1 ├── op-proposer posts output roots └── op-challenger fault proofs ``` ## Settlement — decided **The chain is an OP Stack L2 that settles to Ethereum L1** — Base's sibling, not its child. This is what "Base-aligned" means here: the same stack and the same settlement layer as Base, not settling *onto* Base. The alternative was considered and rejected: | Shape | Settles to | Chain is | Decision | | ----------------------------- | ----------- | ------------------ | ---------------------------------------------------------- | | OP Stack L2, Ethereum-settled | Ethereum L1 | L2, Base's sibling | **Chosen.** Standard, well-supported; one-hop withdrawals. | | OP Stack L3, Base-settled | Base | L3, on top of Base | Rejected — two-hop withdrawals, thinner L3 tooling. | Reasoning for the choice: 1. **One-hop withdrawals.** RWA Chain → Ethereum, directly. The L3 shape needs RWA Chain → Base → Ethereum, each hop with its own challenge period. Exit time matters to institutional RWA investors. 2. **Mature tooling.** Alchemy, The Graph and Blockscout all treat L2s as first-class. L3 support is uneven across all three. 3. **It is what Base itself does.** Same stack, same settlement layer. The cost of this choice: $RWAINC cannot be the gas token without an L1 migration first, because an OP Stack gas token must live on the L1 the chain settles to. That is accepted — see [token-migration.md](/token-migration.md). The chain launches with ETH gas and $RWAINC as a protocol token. Base itself is unaffected either way: it remains an Ethereum L2. The only question this settled was whether the RWA chain stands beside it or on top of it. ## Protocol contracts All contracts are in [contracts/src/](https://github.com/ksrr9351/newblockchinacode/tree/main/contracts/src/README.md). ``` AssetRegistry canonical index of tokenized assets │ (class, jurisdiction, issuer, custodian, valuation, legal ref) │ ├── RWAToken ERC-3643-shaped permissioned security token, one per asset │ │ │ └── ModularCompliance transfer rules for that token │ │ │ └── IdentityRegistry shared KYC/accreditation attestations │ ├── RWAVault permissioned ERC-4626 fund/credit pool │ └── RWAMarketplace compliance-aware secondary market ``` ### The transfer gate Every balance change on an `RWAToken` funnels through `_update`, which is the single choke point (OZ v5 routes mint, burn and transfer through it): 1. Is either party address-frozen? → revert 2. Does the sender have enough *unfrozen* balance? → revert if not 3. Does `ModularCompliance.transferRestriction` return non-zero? → revert `ModularCompliance` checks, in order: sender KYC → sender lockup → receiver KYC → accreditation → jurisdiction allowlist → per-investor balance cap → holder count cap. It returns a numeric code plus a human-readable reason, so UIs and the marketplace can explain a rejection instead of showing a bare revert. `RWAToken.canTransfer` runs the same checks read-only, for pre-flight. ### Issuer powers Securities law requires the issuer to retain control the holder cannot veto. `forcedTransfer`, `recover` and `burn` can all reach partially-frozen tokens — they release the freeze first. `forcedTransfer` still runs the compliance check on the *receiver*, so a forced move can never place tokens in a wallet that is not permitted to hold them. ### Vault redemption model Real-world assets are illiquid, so instant ERC-4626 withdrawal is disabled (`maxWithdraw` and `maxRedeem` return 0). Investors call `requestRedemption`, which burns shares immediately and fixes the asset amount at request time, then `claimRedemption` after `redemptionDelay`. Queued assets are tracked in `pendingRedemptionAssets` and subtracted from `totalAssets`, so funds already promised to redeemers do not inflate the share price for remaining holders. ### Marketplace settlement Sellers escrow tokens on `list`, so a listing is always backed. `fill` checks the buyer against the token's own rules *before* moving money, and settles atomically. Partial fills are supported; payment rounds up so dust never favours the buyer. Note: the marketplace contract holds escrowed tokens, so **the marketplace address must itself be KYC-registered** in the `IdentityRegistry`. This is enforced naturally — `list` reverts otherwise. ## Deferred decisions Two things are deliberately left unconfigured because they need a business decision first, not a technical one: * **Custom gas token ($RWAINC)** — see [token-migration.md](/token-migration.md). * **Chain ID** — must be registered at [ethereum-lists/chains](https://github.com/ethereum-lists/chains) before any public network, so wallets resolve it correctly. The devnet uses 31337 (Anvil's default) purely as a placeholder. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.rwa-chain.io/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.