[Dev Competition] - On-chain Realtokens balances

AlexRLT

🏠 RealToken Aggregator

A modular and scalable Solidity system designed to aggregate RealTokens balances, tailored for the RealT ecosystem.

🔍 Main Feature

Based on a concept similar to Wrappers used with RMM, this system aggregates the hundreds of RealTokens issued by RealT.

Complete reading in a single call per reader of user balances:
✅ Token addresses
✅ Names
✅ Decimals
✅ Balances
Also compatible with RealToken Wrappers (RTW-...) to extract balances deposited on the RMM:
✅ Token addresses
✅ Balances

All 100% on-chain, without TheGraph, no backend, and instantaneous.

⚙️ System Architecture

1. `RealTokenBalanceReader.sol`

Storage contract(s):

Lightweight contract automatically deployed by the Aggregator
Each instance tracks up to 500 RealTokens

2. `RealTokenAggregator.sol`

Main contract (upgradeable via UUPS Proxy) that:

Dynamically manages a list of Readers (RealTokenBalanceReader instances)
Manages a list of RealToken Wrappers (RMM)
Provides centralized and structured user balance reading

🧠 How `addTokensInReaders()` Works

When new RealTokens are listed:

🔍 Checks if each token is already listed via isListed()
📦 Attempts to add it to an existing reader if space is available
🏗️ If all readers are full ➜ automatically deploys a new Reader
🛡️ Prevents duplicates through internal filtering

🧩 Main Functions

🔐 Admin Functions

Function	Description
`addTokensInReaders(address[])`	Adds tokens to readers (automatically deploys a new reader if necessary)
`removeTokenFromReaders(address)`	Removes a token (automatic detection of its location)
`removeReader(uint256)`	Removes a reader by index

Function	Description
`addRmmWrapper(address)`	Adds a RealToken Wrapper to the list
`removeRmmWrapper(uint256)`	Removes an existing RealToken Wrapper

Function	Description
`transferOwnership(address)`	Transfers contract ownership

🧾 Read: Readers (RealTokens)

Function	Description
`getRealtokensReaders()`	Lists readers (index, address, number of tracked tokens)
`getBalancesRealtokens(uint256 index, address user)`	Returns addresses, names, decimals, and balances (raw, formatted using decimals) of a user for a given reader
`isListed(address token)`	Checks if a token is listed and returns its position if so

🧾 Read: RealToken Wrappers (RMM)

Function	Description
`getRmmWrapper()`	Returns registered wrappers list (index + addresses)
`getBalancesRealtokensRMM(uint256 index, address user)`	Returns addresses and balances (raw) of tokens deposited in a wrapper for a user

🔧 Deployment

🔹 1 transaction to deploy the RealTokenAggregator contract
🔹 1 transaction per batch to register initial RealTokens via addTokensInReaders()
🔹 Reader contracts are automatically deployed if needed (max capacity 500 tokens/reader)

🔄 Updates (UUPS)

✅ Deployment of new implementation (v2, v3...)
✅ Upgrade via Proxy
🔁 Proxy address remains the same
✍️ Each implementation can be independently verified

⚠️ Security & Permissions

🔒 Currently, only the owner can add/remove tokens, readers, or wrappers
📖 All read functions are public and unrestricted
🛡️ No access or impact on user funds (read-only)

🚀 Possible Use Cases

✅ Dashboards / Wallets / RealT Explorers
✅ Backend scripts, indexers, bots
✅ RealToken-oriented decentralized applications
.....

⚒️ Updates & Evolution

🧱 The contract is built as a UUPS proxy for future evolutions (new features, fixes, etc.)

🔮 Potential Features to Add

🪪 Create an "UpgradeAdmin" role to authorize certain addresses for critical actions (e.g., upgrades)
🪪 Create a "TokenAdmin" role for standard actions (adding/removing tokens, readers, wrappers)
🔐 Renounce ownership for trustless operation
.....

💰 Costs

Initial deployment: see Deployment section
User-side usage: free (read-only)

🏆 Advantages

🔄 No dependency on TheGraph or external aggregator
On-chain, instantaneous, reliable, always updated retrieval
Easy integration into tools
Smart contract = no "downtime" as long as your RPC works...😄

⭕️ Drawbacks

Limited use to GnosisChain for this contract
Only manages "wallet" & "RMM" balances (practically: does not include liquidity pools)
New tokens must be added as they launch (easily automatable via a bot)

✨ Built for the RealToken community 💙

EzSwim

I like this idea. I sure it will help the developer community greatly, which in turn will benefit the DAO.

AlexRLT Currently, only the owner can add/remove tokens, readers, or wrappers

I am guessing the owner will also be able to update the contract. How do you suggest the DAO defines the owner? Adding/removing tokens will be a weekly task. We can't have a vote every week to add a new RealTokens in an existing/new redear, can we ?

AlexRLT 🔍 Checks if each token is already listed via isListed()
📦 Attempts to add it to an existing reader if space is available
🏗️ If all readers are full ➜ automatically deploys a new Reader
🛡️ Prevents duplicates through internal filtering

I am very curious to see the implementation and gas cost (that the DAO will have to pay each time a new RealToken is sold by RealT if understood correctly) as it could very well be a blocking factor to deploy the solution to Ethereum.

AlexRLT

🏠 RealToken Aggregator

Un système Solidity modulaire et évolutif pour agréger les soldes de RealTokens, conçu pour l’écosystème RealT.

🔍 Fonctionnalité principale

Sur un principe similaire aux Wrappers utilisés avec le RMM, ce système permet d’agréger les centaines de RealTokens émis par RealT.

Lecture complète, en un seul appel par reader*, des soldes d’un utilisateur :
✅ adresses des tokens
✅ noms
✅ décimales
✅ soldes
Également compatible avec les Wrappers RealToken ( RTW-... ) pour extraire les soldes déposés sur le RMM :
✅ adresses des tokens
✅ soldes

Le tout 100% on-chain, sans TheGraph, sans backend, et de manière instantanée.

⚙️ Architecture du système

1. `RealTokenBalanceReader.sol`

Contrat(s) de stockage :

Contrat léger automatiquement déployé par l’Agrégateur
Chaque instance peut suivre jusqu’à 500 RealTokens

2. `RealTokenAggregator.sol`

Contrat principal (upgradeable via Proxy UUPS) qui :

Gère dynamiquement une liste de Reader (instances de RealTokenBalanceReader)
Gère une liste d’adresses de Wrapper RealToken (RMM)
Fournit une lecture centralisée et structurée des soldes utilisateurs

🧠 Fonctionnement de `addTokensInReaders()`

Quand de nouveaux RealTokens sont listés :

🔍 Vérifie si chaque token est déjà listé via isListed()
📦 Tente de l’ajouter dans un reader existant s’il reste de la place
🏗️ Si tous les readers sont pleins ➜ déploie automatiquement un nouveau Reader
🛡️ Évite les doublons grâce à un filtrage interne

🧩 Fonctions principales

🔐 Fonctions "admin"

Fonction	Description
`addTokensInReaders(address[])`	Ajoute des tokens aux readers (déploie automatiquement un nouveau reader si besoin)
`removeTokenFromReaders(address)`	Supprime un token (détection automatique de son emplacement)
`removeReader(uint256)`	Supprime un reader par index

Fonction	Description
`addRmmWrapper(address)`	Ajoute un Wrapper RealToken à la liste
`removeRmmWrapper(uint256)`	Supprime un Wrapper RealToken existant

Fonction	Description
`transferOwnership(address)`	Transfère la propriété du contrat

🧾 Lecture : Readers (RealTokens)

Fonction	Description
`getRealtokensReaders()`	Liste les readers (index, adresse, nombre de tokens suivis)
`getBalancesRealtokens(uint256 index, address user)`	Retourne les adresses, noms, décimales et soldes ( brut, utilisation des decimals pour formattage ) d’un utilisateur pour un reader donné
`isListed(address token)`	Vérifie si un token est listé et retourne sa position si oui

🧾 Lecture : Wrappers RealToken (RMM)

Fonction	Description
`getRmmWrapper()`	Retourne la liste des wrappers enregistrés (index + adresses)
`getBalancesRealtokensRMM(uint256 index, address user)`	Retourne adresses et soldes ( brut ) des tokens déposés dans un wrapper pour un utilisateur

🔧 Déploiement

🔹 1 transaction pour déployer le contrat RealTokenAggregator
🔹 1 transaction par Batch pour enregistrer les realtokens initialement via addTokensInReaders()
🔹 Les contrats Reader sont automatiquement déployés si nécessaire (capacité max 500 tokens / readers)

🔄 Mise à jour (UUPS)

✅ Déploiement d’une nouvelle implémentation (v2, v3…)
✅ Mise à jour via Upgrade with Proxy
🔁 L’adresse du Proxy reste la même
✍️ Chaque implémentation peut être vérifiée séparément

⚠️ Sécurité & Permissions

🔒 Pour l'instant seul le owner peut ajouter/supprimer des tokens, readers ou wrappers
📖 Toutes les fonctions de lecture sont publiques et sans restriction
🛡️ Aucun accès ni impact sur les fonds utilisateurs (lecture uniquement)

🚀 Cas d’utilisation possibles

✅ Dashboards / Wallets / Explorateurs RealT
✅ Scripts backend, indexeurs, bots
✅ Applications décentralisées orientées RealToken
.....

⚒️ Mises à jour & Évolution

🧱 Le contrat est construit sous forme de proxy UUPS pour permettre des évolutions futures (nouvelles fonctions, corrections, etc.)

🔮 Fonctionnalités potentielles à ajouter

🪪 Création d’un rôle "UpgradeAdmin" pour autoriser certaines adresses à effectuer des actions critiques (ex : upgrade)
🪪 Création d’un rôle "TokenAdmin" pour les actions classiques (ajout/retrait de tokens, readers, wrappers)
🔐 Renoncement à la propriété pour un fonctionnement trustless
.....

💰 Coûts

Déploiement initial : voir la section Déploiement
Utilisation côté utilisateur : gratuite (lecture seule)

🏆 Avantages

🔄 Aucune dépendance à TheGraph ou à un agrégateur externe
Récupération on-chain, instantanée, fiable, toujours à jour
Intégration facile dans les outils
Smart contract = pas de "panne" si vous avez un RPC qui fonctionne...😄

⭕️ Inconvénients

Utilisation limitée à GnosisChain pour ce contrat
Ne gère que les soldes "wallet" & "RMM" (concrètement: pas les pools de liquidité)
Il faut ajouter les nouveaux tokens au fil des lancements (automatisable simplement via un bot)

✨ Conçu pour la communauté RealToken 💙

PhilP

Super idée ! 👏

Pourrais tu expliquer comment le Reader détecte un changement de propriétaire d'un Realtoken (sans utiliser TheGraph) ?

AlexRLT

PhilP

C'est ni plus ni moins que le même résultat que la fonction balanceOf() d'un realtoken. Donc tu accèdes a la balance d'une adresse a l'instant ou tu utilises la fonction.

Dans ce cas, ça fonctionne pareil mais pour tout les realtokens stockées sur un Reader. si tu as 1 Reader, alors en 1
requêtes tu pourras récupérer tes balances a l'instant "T" sur 500 tokens

PhilP

AlexRLT
J'ai mal tourné ma question : comment la fonction reader du contrat principal détecte un changement de propriétaire.

Le solde d'un utilisateur pour un Realtoken (via balanceOf), n'est disponible que sur le contrat du Realtoken lui même.
Pour que cette information soit disponible en lecture sur le contrat principal, une logique a du faire la collecte de cette information depuis le contrat du Realtoken pour l'amener sur le contrat principal.
Cette logique tourne j'imagine de façon régulière (fréquence ?), et ne voit donc pas de changement de propriétaire entre deux exécutions.

DRKTT

Hello, cela semble être une très bonne idée.

Par rapport aux inconvénients :

Utilisation limitée à GnosisChain pour ce contrat
Ne gère que les soldes "wallet" & "RMM" (concrètement: pas les pools de liquidité)

Je n'ai pas compris pour quelle raison les autres blockchains et les pools de liquidité ne pouvaient pas être gérées.

Je vois également une autre différence par rapport à TheGraph si j'ai bien compris le concept : On ne peut voir que les balances en cours et pas les balances passées, correct ?

AlexRLT

DRKTT Je n'ai pas compris pour quelle raison les autres blockchains et les pools de liquidité ne pouvaient pas être gérées

On utilise 100% des contrats sur la blockchain donc ça pourrait être répliqué sur ETH sans soucis, mais il faudrait alors stocker aussi les contrats des realtokens sur des readers déployés sur ETH...

Pour les pools, c'est possible a mettre en place sur le même principe, mais avec l'arrivé d'un nouveau système de DEX par Realt ça va sûrement réduire voir supprimer l'intérêt des pools existants.

Sans visibilité là dessus, je n'avais pas envie de perdre du temps a chercher quelque chose a ce niveau.

D'ailleurs jai juste cité des "inconvénients", j'ai pas dit que c'était pas possible 😉

AlexRLT

DRKTT On ne peut voir que les balances en cours et pas les balances passées, correct ?

Comme je l'ai dit a Phil, c'est exactement la même utilisation qu'un appel a balanceOf() d'un contact classique.

Peut-être qu'avec un archive node et un numéro de block on pourrait interroger une situation passée ( je n'ai jamais essayé car pas d'intérêt de mon côté ) mais si ça fonctionne pour un balanceOf, ça devrait aussi le faire avec mes contrats.

DRKTT

AlexRLT

AlexRLT mais avec l'arrivé d'un nouveau système de DEX

Cela fait des années qu'on en parle, je n'ai pas l'impression que cela va arriver rapidement.
C'est important de tout montrer tant que cela existe, y compris par exemple ce qui est déposé sur RMM v2 (je sais pas si tu l'as prévu)

D'ailleurs jai juste cité des "inconvénients", j'ai pas dit que c'était pas possible 😉

Ces inconvénients seront malheureusement rédhibitoires pour son utilisation par Crypt'Alloc

AlexRLT

PhilP

J'utilise les fonctions balanceOf de chaque contrat, il y a pas de stockages de propriétaires 😉

PhilP

AlexRLT
Est ce ainsi que tu fais cela : https://www.perplexity.ai/search/653074dd-92cd-44b1-9446-da62eb44f7d6

AlexRLT

Après le contrat sera upgradable et totalement accessible. rien empêchera de build des nouveautés 🙂

AlexRLT

PhilP plus ou moins 😉

LoganSulpizio

Great idea! I wish I would have had it 😜

AlexRLT

@DRKTT

je vais voir pour ajouter les pools et le RmmV2 😉 j'ai le temps de me pencher dessus de toute façon. la base de la proposition est présente le reste.. du bonus 😃

DRKTT

AlexRLT

Top 🙂 Il ne manquera plus qu'Ethereum et ça sera complet 🙂

AlexRLT

DRKTT

les contrats seront dispo.. si la DAO veut les déployer sur ETH 😉

Par contre ce que je peux te dire... améliorations en cours:

prise en charge du RMM v2
prise en charge des pool uniswap V2
et bonus... tout les prix des oracles pour les realtokens sur le meme principe 🙂

En +/- 7 requêtes, on peut obtenir une valeur USD de tout nos realtokens sur Gnosis si tout est ok 🥸

AlexRLT

ehpst

Aucuns soucis, et oui c'est très proche des multi-call bien que la structure soit différente.

Mon apprentissage personnel est bien plus important que gagner un concours 😉 et si c'est jugé "déjà existant", je n'aurais pas fait ça pour rien malgré tout 😊

Par ailleurs :

AlexRLT
prise en charge du RMM v2
prise en charge des pool uniswap V2
et bonus... tout les prix des oracles pour les realtokens sur le même principe 🙂

Tout les realtokens n'ont pas encore d'oracle d'après l'API donc pour ces derniers, ce sera évidement en fonction de la disponibilité.

Pour le reste.. il restera des tests a faire mais ça avance dans le bon sens

AlexRLT

EzSwim je ne vois pas l'intérêt de mettre au vote le "maintient" à jours de ce contrat... Après, si je suis retenu et qu'il faut absolument faire des votes... Bah écoute 😁😁

Par ailleurs, il y aura toujours la possibilité d'upgrade le contrat avec des rôles, ou bien une liste d'adresses autorisés en plus du owner.

Aucunes utilisations "critiques" avec ces contrats et aucuns risques.

Et oui, sur ETH c'est pas viable du tout, maintenant je suis "amateur". Les optimisations seront sûrement possible ! Sur Gnosis c'est clairement pas problématique.

EzSwim

AlexRLT je ne vois pas l'intérêt de mettre au vote le "maintient" à jours de ce contrat... Après, si je suis retenu et qu'il faut absolument faire des votes... Bah écoute 😁😁

Ok so you will be the owner. Got it, I wanted to make sure I understood properly 🙂

AlexRLT Par ailleurs, il y aura toujours la possibilité d'upgrade le contrat avec des rôles, ou bien une liste d'adresses autorisés en plus du owner.

Cool 👍️

AlexRLT Aucunes utilisations "critiques" avec ces contrats et aucuns risques.

Yup there is no real risk since it's read-only for users 🙂.
The only risk is breaking changes for developers who will use the solution, but people building on the blockchain should be accustomed to this haha

I find your solution to be elegant and the type of infrastructure the DAO needs at the moment. I am truly glad you suggested it! I can't wait to see the code ^^