docs: add RBTC–USDT0 Cross-Chain Lending Starter Kit documentation by entuziaz · Pull Request #439 · rsksmart/devportal

entuziaz · 2025-11-28T23:09:07Z

Title

Complete documentation guide for the RBTC–USDT0 Lending Boilerplate (https://github.com/rsksmart/rbtc-usdt0-lending-boilerplate).

Description

This PR adds a complete documentation guide for the RBTC–USDT0 Lending Boilerplate. It expands the boilerplate into a cross-chain starter kit by providing:

A full explanation of the LendingPool, oracle adapter, and USDT0 contracts
A cross-chain data flow section describing how to extend the boilerplate with LayerZero
Guidance for replacing the mock Umbrella oracle with real Umbrella/RedStone feeds
Testnet and local demo instructions
Use cases and developer extension notes

No contract logic was modified. This PR adds documentation only.
anges.

Testing

N/A

Checklist

I have read and understood the contributing guidelines.
I have followed the style guide and formatting guidelines.
I have added appropriate comments to explain the changes.
I have tested my changes thoroughly.

Refs

Code Repo: https://github.com/rsksmart/rbtc-usdt0-lending-boilerplate

vercel · 2025-11-28T23:09:11Z

@entuziaz is attempting to deploy a commit to the IOV Labs Team on Vercel.

A member of the Team first needs to authorize it.

Removed project illustration diagram from the tutorial.

vercel · 2026-03-05T14:13:27Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
devportal-rootstock	Ready	Preview, Comment	Mar 11, 2026 9:07am

owans · 2026-03-05T14:50:05Z

This guide shows how to deploy and use a cross-chain lending starter kit on Rootstock. It describes the architecture, setup, deployment, and how to use a frontend dApp. The guide is structured for developers who know EVM but are new to Rootstock or cross-chain protocols. Architecture diagrams and UI screenshots improve understanding.

Still, the documentation could be better in terms of clarity, completeness, correct commands, and accurate code snippets. The code execution results point out that standalone JavaScript snippets lack context, which can confuse readers trying to run them.

Review: Docs/02-developers/09-use-cases/defi/cross-chain-lending-rbtc.md (overall document)

The document's overall structure is good. It begins with an introduction and moves through setup, core concepts, and advanced considerations. The Docusaurus-style metadata (sidebar_label, title, description, tags) is right for modern documentation. The "comprehensive tutorial" banner makes expectations clear.

A small issue is that "starter kit" is used repeatedly in the title and description, which could be shortened. Active voice and imperative mood are used consistently, which is good.

Review: table of contents

The table of contents is clear, well-structured, and shows the document's sections accurately. It provides a good overview for readers to navigate the detailed content.

Review: introduction

The introduction clearly states the tutorial's purpose and scope, explaining what readers will learn. The target audience is clear. A screenshot and architecture diagram early on are great visual aids to quickly understand the project's goal and structure. The alt text for the images is descriptive.

Review: why build on rootstock?

This section effectively points out the main benefits of building on Rootstock, which is important for convincing developers to use the platform. The points are short and apply to DeFi applications.

Review: core architecture

This section breaks down the protocol into logical layers and describes key contract responsibilities. This is explained well and uses clear language.

Code

The Solidity excerpt from LZReceiver.lzReceive is accurate and shows the message dispatch logic well. The _isSolvent function snippet clearly shows the LTV check and oracle integration, including a testnet fallback. The OracleRouter snippet is also clear.

Diagrams

Figure 3 showing the high-level contract interaction is useful, although its title could be more specific (e.g., "Contract Interaction Diagram").

Review: prerequisites

The list of prerequisites is straightforward. It is good to specify minimum versions for Git and Node.js.

Clarity

"npm or yarn: package manager" – It would be clearer to state "npm or Yarn: a package manager" to explicitly show it's a choice.
"Hardhat: installed locally (no global install needed)" – This is a useful clarification for newer developers.
"MetaMask: or similar Web3 wallet, configured with Rootstock testnet" – Provide a quick link or reference to instructions on how to configure MetaMask for Rootstock testnet, as this is a common first problem.

Review: cloning and initial setup

The instructions are clear and standard for repository cloning.

Review: environment configuration

This section provides important information for setting up the .env file.

Security

The ⚠️ Never commit this file. In production you would use a secrets manager or hardware wallet. warning is important and well-placed.

Completeness

LZ_ENDPOINT: It would be helpful to provide a link or a quick instruction on how to find the correct LayerZero testnet endpoint for Rootstock, as this can change or be hard to find.
PRIVATE_KEY: Emphasize that this account needs testnet funds (rBTC) for deployment, which is mentioned later but is an important prerequisite for deployment.

Review: installing dependencies

The commands for installing dependencies are correct and clearly specify which directory each npm install command should be run in.

Review: compiling contracts and generating abis

The instruction npx hardhat compile is correct. The explanation of output directories and the hot-reload feature for React is helpful context.

Review: running the test suite

This section clearly explains how to run tests and lists main test files. The command for running a single test file is also useful.

Troubleshooting

The advice to delete artifacts/ and cache/ for test failures is a good troubleshooting tip, though it's also present in the dedicated troubleshooting section. Consistency is fine here.

Review: deployment walkthrough

This section explains the deployment script and its output.

Command correctness

npx hardhat run scripts/deploy.js --network rsktest is correct.

Completeness

The "Addresses will vary; keep them for the frontend or explorer verification" note is important.

Verifying on explorer

The verification command is provided, but it's important to clarify which address and constructor arguments to use. While it's implied that addresses come from the deployment output, a quick example using one of the deployed contracts would be clearer.

Review: using the frontend dapp

This section shows how to use the dApp.

Command correctness

env pm run dev – The command env is not a standard part of npm run dev. It seems to be a typo for npm run dev or a specific setup that's not general. Assuming it's npm run dev, it needs correction.

Prerequisites

"Proper MetaMask configuration is important. Make sure an RSK testnet network entry exists and the current account holds at least 0.001 rBTC. Use the Rootstock faucet to top up if necessary." – This is well-placed and important information.

Code execution results analysis (snippet 1)

The getContracts function snippet is shown as [JAVASCRIPT] Code: and when executed standalone, it fails with Error: Cannot find module 'ethers'. This is expected because ethers is a project dependency, not globally available, and the snippet is missing an npm install step. The documentation correctly notes that ABIs are imported directly from the Hardhat artifacts/ directory, which is why a successful compile is required before npm run dev. It does include npm install steps. This suggests the snippet executor's environment did not have ethers installed. The documentation's instruction for this is correct, but the snippet itself, when extracted, needs its full context to run directly.

Completeness

The frontend folder structure diagram is a good addition for understanding the project layout.

Review: protocol mechanics

This section goes into the smart contract logic for borrowing, repayment, withdrawal, and solvency.

Technical accuracy

The Solvency math formula and explanation are clear and correct.

Code

The Solidity snippets are accurate and help show the described mechanics.

Review: oracle setup and pricing model

This section clearly explains the oracle architecture, showing the difference between market assets and accounting units.

Technical accuracy

The explanation of OracleRouter allowing flexible price source upgrades is a main architectural benefit.

Code execution results analysis (snippet 2)

The await oracleRouter.setOracle(rbtcAddress, adapter.address); snippet fails with ReferenceError: oracleRouter is not defined. This is because the snippet is shown in isolation. In a real deployment script (deploy.js), oracleRouter would be a contract instance obtained via ethers.getContractAt or ethers.deployContract. The documentation shows it as part of "In deployment (or manually), register an oracle," suggesting it is used in a script. The error comes from trying to run it without context. The documentation itself describes the process correctly but could provide a simpler, more complete code example for context.

Review: cross-chain flow explained

This section clearly explains the LayerZero cross-chain mechanism, describing user actions, receiver validation, and the deposit/borrow flow.

Clarity

The clarification ⚠️ The system operates on signaling rather than bridging. The rBTC is already on Rootstock; you are only sending a message to credit the collateral. is important and well-placed.

Security

The "Timing risk" explanation is a good point about security and design.

Review: known limitations

This is a good and honest section. Explicitly stating limitations, especially for a starter kit, is important for developers who want to extend it for production use.

Completeness

It covers testnet issues, mock behaviors, and missing core DeFi features (liquidations, interest, governance).

Review: security considerations

This section repeats the README's security section with added context, which is useful.

Importance

The 🔐 Important: this code is not audited. warning is important and clearly placed.

Completeness

It covers role isolation, oracle staleness, bridge trust, lack of liquidations/interest, and owner privileges. This is a thorough list for a starter kit.

Review: troubleshooting and tips

This section is helpful, offering solutions to common issues during development and deployment.

Completeness

It addresses test failures, deployment errors, frontend issues, LayerZero configuration, and oracle problems. The tips are practical.

Review: faq & next steps

This section answers common questions and provides a roadmap for extending the project.

Clarity

The answers are concise and practical. The "roadmap" provides good guidance for future development.

Terminology

"What is USDT0?" is a good question to answer, explaining its role as an accounting unit.

Review: credits

Properly attributing the original creators and inspirations is a good practice and well-done here.

Summary of code execution results:

The errors from the JavaScript snippets are mostly because the execution environment is missing the needed context (e.g., ethers being installed and imported, oracleRouter being defined as a contract instance). The documentation's instructions for setting up the environment and compiling contracts are correct, but the snippets themselves, when taken alone to run directly, lack the surrounding code to run. This shows a common challenge in documentation where snippets demonstrate a concept rather than offering a full, runnable block of code.

Overall grammar and style:

The documentation is mostly well-written with good grammar, following technical writing best practices.

Active voice: Used often.
Headings: Sentence case is mostly followed.
Lists: Both types are used effectively.
Accessibility: Alt text for images is provided.
Contractions: Used correctly.
Imperative mood: Used for instructions, which is good.

The structured findings suggest some small grammar improvements or clarifications.

Clarity and completeness:

The document is clear and complete. The main areas to improve are:

Adding direct links for MetaMask configuration and LayerZero endpoints.
Giving more context for standalone code snippets to make them runnable right away or to make their intended execution environment clearer.
Correcting the typo in the frontend run command.

Overall, this is good documentation that works well.

💬 Comment posted via Revue - Documentation Review Tool

owans · 2026-03-05T14:53:15Z