¶ Preamble: Why are REGs allocated to you? ⭐
Each time an asset issued in the ecosystem is tokenized, the DAO allows its tokenization partners to allocate an amount of USDREG (convertible only to REG) to customers who have purchased and held the tokens for a variable period depending on the asset. These USDREGs are convertible into REG at any time at the market price.
Currently, the amount of USDREG corresponds to the fees charged by RealT for its property sourcing work and is allocated at the time of the first revaluation of the property.
RealT has announced its intention to evolve the criteria for allocating USDREG rights to be applicable to all types of tokenizations RealT offers, not just traditional real estate (loan tokenization, for example, which does not require revaluation).
Before the creation of REG, this amount was paid in SOON tokens, whose value was 1 USDREG.
Once the REG claim application is operational, SOON will disappear, and allocation at the first revaluation will be made directly in USDREG (see RIP00009).
Property revaluations are performed by companies independent of RealT.
The cost of this action is becoming high (especially for multi-family properties) and is leading RealT to postpone these revaluations, which were originally planned to be annual.
In the future, the distribution of USDREG should no longer be linked to the revaluation, but to a delay after tokenization.
¶ The application to claim your REG ⭐
https://claim.realtoken.network/
- The application runs on the Gnosis blockchain.
- You must connect one of the following wallets:
- the one declared as receiving the Realtokens, on Realt.co (at the time the conversion is launched): to claim the USDREG ($ convertible to REG) corresponding to the Soon received over several years.
- the one holding the Realtokens, which will be revalued subsequently (once the Soon distribution has stopped).
- Choose your presentation mode (language, background).
- Make sure you are in "REG Claim" and not "Genesis".
Note: Walletless users will need to migrate to Realtoken Wallet or other compatible wallet to connect to the application, then ask support to make the claim on the new Wallet for the tokens allocated to the Walletless. FR Help Link
Once logged in, you will see:
- The amount of USDREG allocated to you (20 in the image),
- The current REG parity in $ (1.93),
- The corresponding number of REG (10.34), which you can claim (only in full),
- The amount of USDREG you have already claimed (100), before a new allocation,
- The delegation option (see next chapter),
- The Auto Claim option
You can authorize the automatic execution of claims for you (by a robot), as soon as USDREG is allocated to you. allocated (maximum 24-hour delay).
A fee may be charged for this service (currently 0%).
¶ Delegate Claim
It is possible to delegate another address to claim and collect your REG (for example, in the event of a corrupted wallet):
- Log in to the application with the initial wallet (0x69…94a in the image),
- Check the claim with another address box, and indicate the delegated address (0x…C08 in the image). Then sign this delegation authorization with the initial address. 3. The application indicates that you must change your login address to claim.
- Log in with the delegated address (0x…C08 in the image).
- Launch the claim.
- The claim will send the REG allocated to the initial address to the delegated address.
¶ What to do with the claimed REG
To know what to do with the claimed REGs, you still need to understand what they are, what they entitle you to now and in the future.
To do this, a little quiz has been included during the claim process: in the form of information/questions.
After 10 correct answers, you can check the box to avoid further questions.
¶ How it works ⭐⭐
¶ Before the creation of the reclamation contract
During the Soon period (2021 to March 2025) and before the creation of the REG reclamation contract (Vault):
- Following each revaluation of a Realtoken, RealT launched the mint of the corresponding Soon,
- These Soon were allocated to the wallets of the Realtoken owners at the time of the revaluation.
To initialize the reclamation contract, the Soon tokens are converted into USDREG and then destroyed:
3. RealT initiates the Soon token conversion,
4. Collects all wallets holding Soon tokens and their quantity,
5. The Soon tokens are converted into USDREG,
This amount for each wallet is recorded in an off-chain file (Merkel Tree, the converted Soon tokens are allocated for each address to the last known Realtoken delivery address on the user's realt.co website,
6. The Soon tokens are destroyed (burned).
All of the above actions are executed only once, when the reclamation contract is created.
Note: The "Merkel tree" solution was chosen for storing each person's rights in USDREG, because it is the solution generally used for airdrops and distributions by claim. This off-chain solution is particularly more economical when the number of beneficiaries is large.
¶ User Claim
Once the "Merkle Tree" file is initialized (the first time using accumulated Soons):
- REG claims can be requested:
- from the claim application, which displays the number of USDREG,
- or directly on the contract from the user wallet (a more complex solution).
- The claim is executed by the Vault conversion smart contract.
- It verifies, based on the Merkle Tree root transmitted to it, that the user has the corresponding rights.
- It calculates the number of USDREGs based on the Merkle Tree data and the USDREGs already claimed (whose value it stores) to determine the number of USDREGs that can be claimed. This amount is then converted into REGs based on the Oracle price.
- It requests the REG contract to create (mint) the REGs.
- The new REGs are transferred to the user's wallet.
- Subsequent revaluations/distributions (after the Soons disappear) will be made directly in USDREGs, by updating the Merkle Tree. This update will make new USDREG available for claiming appear in the application.
The new USDREG will be allocated to the address holding Realtokens at the time of the snapshot (unlike the USDREG entitlement from the Soon conversion, which is allocated to the last RealToken delivery address registered in your realt.co account).
If the address holding USDREG has been corrupted, it is possible to simply sign with the corrupted address, delegating the claim to another address. This other address will then be able to claim and receive the REG.
¶ "Automatic" Claim
The execution of the claim by the Vault smart contract can be triggered:
- either manually, at any time, by the user (the parity is then chosen),
- or automatically by a bot after the allocation of new USDREG (the parity is not chosen). The latter mode requires prior authorization.
- The automaton will monitor Merkel Tree updates for registered users, then trigger a REG claim for the affected users.
- Depending on the configuration of the Vault conversion smart contract, an automatic claim fee may be applied (0% initially) to encourage the creation of such an automaton and cover the associated transaction fees (enabling fees will require a governance vote).
- The Vault will request the minting of two amounts of REG: one for the fees and one for the user.
- The REG contract mints the fee REGs into the automaton's wallet.
- The REG contract mints the user's REGs into the user's wallet.
Note: This feature cannot be combined with a delegated claim (which is similar to a user claim).
¶ Address
Smart contract:
- Soon: 0xaa2c0cf54cb418eb24e7e09053b82c875c68bb88
- REG: 0x0aa1e96d2a46ec6beb2923de1e61addf5f5f1dce
- Vault: 0x71eb2b2518556700f5b778b9cc313bfe8de5086e
- Oracle: 0x86339b40e588f774bd766eB70D47bEFBe68B6F64
Merkel Tree (OffChain): https://github.com/real-token/vault-merkle-data/blob/main/dao/usdreg_convertion/current.json
This file can be backed up by the community to remain available in all situations. The latest version, whose root is registered in the claim contract, remains valid even if the interface or source file no longer exists.
¶ Vault Contract Operation Details ⭐⭐⭐
The smart contract address above is the Proxy's (unchanged) address, which points to the following implementation (which may vary depending on updates): https://gnosisscan.io/address/0x94223f067dbf9b43ed3bfea1d02cc1839031b6d2#code
The program manages the conversion and distribution of REG tokens, based on USDREG amounts recorded on a Merkel Tree and the REG value provided by the Oracle.
¶ Key Features
- Roles and Permissions: The contract uses OpenZeppelin's access control system to manage different roles (administrator, operator, pauser, and upgrader) to secure critical operations.
- Token Management: It interacts with the REG token, allowing users to claim REG tokens based on USDREG amounts, while verifying Merkle proofs to ensure eligibility.
- Claiming Features: Users can claim tokens either directly or through a delegate. The contract also supports automated claiming features. Walletless claims exist, but are not implemented off-chain: Walletless accounts will need to migrate to a new wallet.
- Timestamp Management: The contract includes mechanisms to verify that claims occur within a defined time period, preventing claims outside of this period.
- Bridge and Transfers: It also allows tokens to be transferred to other chains (bridge) and manage the fees associated with these transfers.
- Updates: The contract is designed to be updated via an upgrade mechanism, allowing new features to be added or bugs to be fixed without losing the contract's state. 7. Events: It emits events to track important actions, such as token claims, parameter updates, and errors.
¶ Validation with Merkle Proof
Validation with Merkle Proof works by verifying that a user's information (address and amount) is included in a data structure called a Merkle tree.
Execution in the program:
- Leaf Generation: For each claim, a leaf is generated by hashing the user's data (address and amount) with the keccak256 function. This creates a unique hash that represents that claim.
-
Proof Verification: The _validateMerkleProof function takes as input the user's address, the amount, the expected Merkle root, and an array of Merkle proofs. It verifies that the Merkle proof is valid for the user and the specified amount.
Link to corresponding code
-
Merkle Tree Verification: The _verifyAsm function uses an assembly approach to traverse Merkle proofs. It takes each node of the proof and combines it with the leaf to reconstruct the hash until it reaches the Merkle root. If the reconstructed root matches the expected Merkle root, it means the claim is valid.
Link to the corresponding code
-
Rejection of Invalid Claims: If the verification fails, the contract rejects the claim by throwing an error, thus ensuring that only valid claims, which match the structure of the Merkle tree, are accepted.
¶ Claim Mode
The main claim modes in the contract are:
¶ User Claim (lines 176 to 200)
- Function: claim
- Description: This mode allows a user to claim REG tokens based on an amount in USDREG.
- Process:
- The user calls the claim function with the amount they wish to claim and a Merkle proof.
- The function verifies that the contract is not paused and that the timestamps are valid.
- It verifies that the Merkle proof is valid for the user and the specified amount.
- It verifies the amount already claimed by the user to avoid double claims.
- If all checks pass, the contract calculates the amount of REG to issue and mints the REG tokens for the user.
¶ Claim by Delegate (lines 302 to 336)
- Function: claimByDelegate
- Description: This mode allows a user to designate a delegate to claim tokens on their behalf.
- Process:
- The user provides claim information (account address, amount, recipient) and a signature to prove authorization.
- The function verifies that the contract is not paused and that the timestamps are valid. 3. It validates the signature to ensure that the delegate is authorized to act on the user's behalf.
- As in the user-initiated claim method, the Merkle proof is validated, and the amount already claimed is verified.
- If everything is valid, the contract mints the REG tokens for the recipient.
The interface for this function sends the REG to the delegated address.
In a future update of the interface: it will be possible to delegate the claim without sending the tokens to the delegate, but to an address determined at the time of signing.
Link to the corresponding code
¶ Automatic Claim (lines 552 to 640)
- Function: claimByAutoClaim
- Description: This mode allows users to automatically claim REG tokens without having to manually initiate the claim.
- Process:
- The user calls the function with an array of claim structures.
- The function checks that the contract is not paused and that the timestamps are valid. 3. For each claim, it checks whether self-claim is enabled for the recipient.
- It validates the Merkle proof and verifies the amount already claimed.
- REG tokens are minted for the recipient, and fees may apply if configured.
Link to the corresponding code
Automatic claims are executed:
- by an automaton created by RealT
The script searches for autoclaims on Thegraph, balances those already claimed, retrieves the Merkel, sorts them to keep only those with USDREG to claim, and performs batch transactions for the claim. First execution - or by anyone, manually or automatically. Here's an example:autoclaim_en.pdf
¶ REG Price Oracle
The REG Price Oracle contract is based on Chainlink code and includes:
- the smart contract https://gnosisscan.io/address/0x86339b40e588f774bd766eB70D47bEFBe68B6F64/advanced#code
- a Chainlink infrastructure to automate on-chain and off-chain price surveys across multiple sources and perform calculations aimed at preventing price manipulation. The calculation takes into account trading volumes, time spent at a price, differences between price sources, it creates a weighting to avoid manipulations, the update rate with the calculated value is updated onchain every 24 hours by a Chainlink automaton.
In the graph below, you can see the Time-Weighted Average Price (TWAP) calculated by the Oracle compared to the REG spot price.
¶ Why use this calculation method for REG conversion?
-
Mitigate market manipulation: TWAP calculates the price over a 24-hour period, reducing the risk of manipulation in illiquid markets like REG, where spot prices can be easily distorted by small transactions.
-
Prevent downward spirals: By not reacting immediately to price drops, TWAP stabilizes the market and prevents panic selling, which can lead to a downward spiral for illiquid tokens.
-
Ensure Price Stability: TWAP offers a constant conversion rate based on daily averages, protecting REG from spot price volatility, especially in low-liquidity environments. It guarantees fairness by ensuring that all users can obtain the same amount of REG for a given credit over a given time window.
-
Support Self-Balancing to Protect REG: TWAP adjusts REG issuance based on price movements; users receive less REG when prices fall and more REG when prices rise.
-
Designed for Conversion: The mechanism is designed to allow users to choose when to convert, rather than serving as a real-time trading tool.