docs: added ussd use case demo

[jayzalani]

Title

Docs: Add USSD-Based Decentralized Finance on Rootstock

Description

Purpose: Add documentation for a USSD-based Rootstock integration that enables decentralized financial services on feature phones without internet access or a smartphone.

Context: No existing documentation covers connecting the Rootstock stack to telecom USSD gateways. This contribution fills that gap with a working proof-of-concept covering smart contract design, an off-chain relay server, and Africa's Talking gateway integration. The system allows users on basic GSM phones to perform P2P transfers and request micro-loans directly on the Rootstock network.

Changes:

• overview.md - Problem statement, system architecture diagram, deployed contract details, and page navigation
• architecture.md - USSD session lifecycle, relay server state machine, component breakdown, gas/fee model, and security considerations
• project-setup.md - Hardhat 3 scaffolding, InclusiveDeFi.sol contract, Rootstock Testnet network config, and Ignition deployment steps
• relay-server.md - Express relay server, session guard for duplicate transaction prevention, fire-and-forget transaction pattern, granular error handling, and Africa's Talking USSD channel setup
• demo-and-testing.md - End-to-end demo with screenshots, curl test commands for all USSD flows, Hardhat unit test commands, and on-chain verification via Rootstock Testnet Explorer

Screenshots/GIFs

Screenshots are included in relay and server.md and in demo-and-testing.md covering the full USSD flow:

• Server startup
• Main menu
• Balance check
• P2P transfer (4 steps)
• Micro-loan confirmation

Testing

Verification: Ran yarn build locally across all locales (en, es, ja, ko). Build completed successfully with no errors. Ran yarn check-links:external across 9054 links. 7 broken external links found: 5 are auto-generated self-referencing GitHub links that will resolve after merge, 2 are pre-existing repo issues (rsksmart/bridge/releases, gateway-arbitrum.network) unrelated to this contribution. Zero new broken links introduced.

Output:

[markdown-source-plugin] Successfully copied 287 markdown files
[markdown-source-plugin] Copying image directories...
[markdown-source-plugin] Successfully copied 0 image directories
[SUCCESS] Generated static files in "build\ko".
[INFO] Use `npm run serve` command to test your build locally.

yarn check-links:external
Total links checked: 9054
External links found: 3776
Unique external URLs: 3749
Broken external links: 7
Unreachable links: 1
Redirect links: 0

Quality Checklist

• Guidelines: I have read and followed the Contributing Guidelines.
• Vale Linter: I have run vale locally and resolved all Rootstock.Robotics and style warnings.
• Rootstock Engineer Voice: I have removed AI-style "fluff".
• Structural Clarity: I have replaced em dashes with commas or periods and ensured there are no stacked headings.
• Code Quality: Technical comments are placed above the code line, not inline at the end.
• Terminology: I am using rBTC (not Smart Bitcoin) and Rootstock (not RSK).

Refs

• submission of Hacktivator: https://hacktivator-marketplace.rootstock.io/idea/68
• Africa's Talking USSD Docs: https://developers.africastalking.com/docs/ussd/overview
• Rootstock Testnet Explorer: https://explorer.testnet.rootstock.io
• Rootstock Testnet Faucet: https://faucet.rootstock.io

[vercel]

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

A member of the Team first needs to authorize it.

[jayzalani]

@owans can you review this submission for hacktivator idea no. 68

[owans]

This documentation offers a guide for integrating USSD with Rootstock DeFi, covering architecture, implementation, and testing. The overall clarity is good, and the step-by-step instructions are generally easy to follow. The technical depth is appropriate for the target audience of developers.

However, several areas can benefit from editorial improvements, primarily concerning consistency in formatting (especially code blocks), minor grammatical fixes, and adherence to the specified style guide. Some phrasing can be tightened for better clarity and conciseness.

The review will cover each file individually, pointing out specific issues and offering clear recommendations to improve the documentation's quality and user experience.

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/category.yml

Clarity and readability:
The description has a minor grammatical error.

Recommendation:

• Correct the preposition "Rootstock" to "on Rootstock".

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/architecture.md

This document provides an overview of the system's architecture and data flow. It explains complex concepts clearly and uses a logical structure.

Grammar and language:

• Sentence structure: Some sentences could be more concise or rephrased for better flow.
• Consistency: Code block formatting is inconsistent.

Clarity and readability:

• Format all code snippets, especially terminal output or text configurations, as code blocks for readability.

Recommendations:

• Introduction: Rephrase the opening sentence for better flow and conciseness.
• Components overview: Rephrase the introductory sentence to be more active and direct.
• Code block formatting: Apply plaintext or bash code block formatting where appropriate for commands, configurations, and expected outputs.
• Passive voice: Convert sentences from passive to active voice where appropriate (e.g., "The relayer wallet must be kept funded..." to "Keep the relayer wallet funded...").
• Terminology: Standardize text === "" to text === "".
• Consistency: In the "Security Considerations" and "Gas & Fee Model" sections, convert bullet points to direct, imperative statements. This aligns with the style guide's preference for imperative mood and active voice.
• Network configuration: Rephrase the concluding sentence to be more direct.

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/demo-and-testing.md

This page offers a practical guide to testing the USSD-RSK bridge. The demo overview is clear, and the curl commands are helpful. The "Known Limitations" section is useful.

Grammar and language:

• Punctuation: Some sentences are missing periods or have incorrect punctuation.
• Clarity: Some phrasing can be slightly ambiguous or less direct.
• Consistency: Code block formatting for curl commands and expected responses should be consistent.

Clarity and readability:

• The curl command sections need proper code block wrapping for commands and expected outputs.
• Headings for the "Known Limitations" section should show that the list items are recommendations for improvement.

Recommendations:

• Introduction: The introductory sentence should use consistent terminology and correct grammar.
• curl commands: Wrap all curl commands in bash code blocks and their expected responses in plaintext code blocks.
• Verifying transactions on-chain: Rephrase for conciseness and clarity.
• Known limitations:
  • Change the heading to "Known Limitations and Recommended Improvements" to better reflect the content.
  • Rephrase the first limitation about the processedSessions Set for clarity.
  • Improve the phrasing for the "Post-broadcast reverts are silent to the user" limitation.
  • Clarify the "No formal meta-transaction standard" limitation.
  • Make the "Private key in .env" limitation more concise.
  • Present each limitation as a direct statement followed by the recommended improvement.

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/Implementation

This page provides a detailed step-by-step implementation guide. The structure is logical, and the code snippets are well-placed.

Grammar and language:

• Terminology: Inconsistent phrasing and capitalization for "InclusiveDeFi".
• Conciseness: Some sentences could be more concise.

Clarity and readability:

• Code blocks for npm commands, .env, .gitignore, and package.json are missing or improperly formatted.
• The solidity, typescript, dotenv, and json code blocks should be properly formatted.

Recommendations:

• Title: Standardize the capitalization of "Implementation Guide" to match other titles.
• Note: Correct the grammar and phrasing of the note about InclusiveDeFi.
• Prerequisites: Use "v18+" instead of "v18 or later" for brevity.
• Smart contract section:
  • Rephrase the introductory sentence for clarity.
  • Enclose the Solidity code in a proper solidity code block.
  • Rephrase the notes about applyForLoan() and contract design for better flow and conciseness, adhering to the imperative mood.
• Hardhat configuration section:
  • Place the npm install command in a bash code block.
  • Place the hardhat.config.ts code in a typescript code block.
• Environment variables section:
  • Place .env content in a dotenv code block.
  • Place .gitignore content in a gitignore code block.
  • Rephrase the warnings for conciseness.
• Deploy the contract section:
  • Place the npx hardhat command in a bash code block.
  • Place the example output in a plaintext code block.
• USSD relay server section:
  • Place the index.ts code in a typescript code block.
• Start the server: Place the command in a bash code block.
• Exposing the server: Place ngrok commands and output in bash and plaintext code blocks, respectively.
• Step 7: Testing the flow: Place curl commands and npx hardhat test in bash code blocks.
• package.json reference: Place the package.json content in a json code block.
• Limitations and future work:
  • Rephrase the first bullet point for conciseness and clarity.
  • All bullet points should use the imperative mood.

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/overview.md

This file serves as a good introduction to the USSD-Rootstock DeFi concept. It clearly articulates the "why" and "who" before diving into the "what."

Grammar and language:

• Punctuation: Missing colons or incorrect use of dashes.
• Conciseness: Some sentences can be tightened.
• Terminology: "Internet-free" is used; ensure consistency.

Clarity and readability:

• The core message is clear, but minor phrasing adjustments can improve impact.

Recommendations:

• Introduction: Improve the flow and punctuation of the introductory paragraph.
• Why this matters:
  • Correct the sentence structure and punctuation.
  • Refine the phrasing for better impact.
• Who this is for: Rephrase the sentence for conciseness and directness.
• System at a glance:
  • Rephrase the introductory sentence to be more active.
  • Use consistent phrasing for "Off-Chain Relay Layer."

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/project-setup.md

This page guides users through setting up the project and deploying the smart contract. The steps are clear and well-ordered.

Grammar and language:

• Terminology: Inconsistent capitalization of InclusiveDeFi.
• Punctuation: Missing commas or periods.
• Clarity: Some explanations could be more direct.

Clarity and readability:

• Code blocks for npm commands, .env, .gitignore, hardhat.config.ts, InclusiveDeFi.sol, InclusiveDeFi.ts, and package.json are missing or improperly formatted.

Recommendations:

• Title: Correct the capitalization of "Smart Contract Deployment".
• Note: Correct the grammar and capitalization in the note about InclusiveDeFi.
• Prerequisites: Add "is recommended" to the end of the sentence about familiarity with Solidity and Hardhat.
• Scaffolding the project section:
  • Place mkdir and npx hardhat commands in bash code blocks.
  • Rephrase the note about Hardhat's initializer for clarity.
  • Place npm install commands in bash code blocks.
  • Place the package.json reference in a json code block.
• Environment variables section:
  • Rephrase the introductory sentence.
  • Place .env content in a dotenv code block.
  • Rephrase the warning for conciseness.
  • Place .gitignore content in a gitignore code block.
• Hardhat configuration section:
  • Rephrase the introductory sentence.
  • Place hardhat.config.ts content in a typescript code block.
  • Rephrase the note about chainType: "l1" for clarity and correct formatting of the RPC URL.
• The smart contract section:
  • Rephrase the introductory sentence.
  • Place InclusiveDeFi.sol content in a solidity code block.
  • In the "Contract Design Notes," use consistent formatting for balances[] and deposit().
  • Rephrase the note about applyForLoan() for clarity and conciseness.
• Ignition deployment module: Place InclusiveDeFi.ts content in a typescript code block.
• Deploying to RSK testnet:
  • Place the npx hardhat command in a bash code block.
  • Place the example output in a plaintext code block.
• Verifying the deployment: Rephrase the sentence for clarity and conciseness.
• Next steps: Rephrase for conciseness.

---

Review: docs/02-developers/09-use-cases/ussd-rootstock-defi/relay-server.md

This page details the relay server implementation and its integration with Africa's Talking. The breakdown of the USSD state machine is helpful.

Grammar and language:

• Punctuation: Missing commas.
• Conciseness: Some sentences can be tightened.

Clarity and readability:

• Code block formatting for the index.ts file is missing.
• Code blocks for npm, ngrok commands, and their outputs are missing.

Recommendations:

• Title: Correct the capitalization of "Gateway Integration".
• How the relay server works:
  • Rephrase the introductory and follow-up sentences for better flow and clarity, using POST /ussd and text field formatting.
• Creating the relay server: Wrap the entire index.ts code in a typescript code block.
• Running the server: Format the command and image caption correctly.
• Exposing the server with ngrok: Place ngrok commands and output in bash and plaintext code blocks respectively. Rephrase the note about the ngrok URL for conciseness.
• Registering with Africa's Talking:
  • Format the ngrok URL correctly with backticks.
  • Rephrase the note about ngrok's web interface for clarity.
• What each transaction looks like on-chain:
  • Rephrase the introductory sentence to use "performs the following steps".
  • Rephrase the conclusion about RSK's block time for better flow.
• Next steps: Rephrase for conciseness.

---

Review: docs/02-developers/09-use-cases/index.md

This is an index file that uses Docusaurus's Filter component. It provides an overview of different use cases.

Consistency:

• The subtitle values for the FilterItem components are inconsistent in capitalization.

Recommendations:

• FilterItem subtitles: All FilterItem subtitles should use consistent capitalization (e.g., "USSD" instead of "ussd", "AI" instead of "ai").

---

💬 Comment posted via Revue - Documentation Review Tool

[owans]

Please remove H1s as the meta title already displays the title of the page

[owans]

Suggested change

	### 3. Ethers.js + RSK JSON-RPC
	### 3. Ethers.js + Rootstock JSON-RPC

[owans]

Please update to use the Rootstock RPC API: https://dev.rootstock.io/developers/rpc-api/rootstock/

[vercel]

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 0:21am

[jayzalani]

thank you for reviewing this, will update these changes.

[jayzalani]

Hi @owans, I’ve pushed a new commit addressing the review feedback. I also removed the Implementation file that I had accidentally included earlier it was only for my personal understanding during development.
Please take another look and let me know if anything else needs to be updated.

[owans]

Hi @owans, I’ve pushed a new commit addressing the review feedback. I also removed the Implementation file that I had accidentally included earlier it was only for my personal understanding during development. Please take another look and let me know if anything else needs to be updated.

Noted @jayzalani

[owans]

Suggested change

---

[owans]

Suggested change

---

[owans]

Suggested change

---

[owans]

Suggested change

# USSD-Based Decentralized Finance on Rootstock

[owans]

npm run start-bridge
npm error Missing script: "start-bridge"
npm error
npm error To see a list of scripts, run:
npm error npm run
npm error A complete log of this run can be found in: /Users/owanate/.npm/_logs/2026-03-06T15_48_31_189Z-debug-0.log
owanate@Owanates-MacBook-Pro ussd %

[owans]

Add a note to ensure to add the start-bridge script command in package.json as earlier instructed

[owans]

ussd % npm run start-bridge

ussd@1.0.0 start-bridge
tsx index.ts

[dotenv@17.3.1] injecting env (2) from .env -- tip: 🔐 prevent building .env in docker: https://dotenvx.com/prebuild
RSK-USSD Bridge running on port 3000
/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/utils/errors.ts:698
error = new Error(message);
^

Error: network does not support ENS (operation="getEnsAddress", info={ "network": { "chainId": "31", "name": "unknown" } }, code=UNSUPPORTED_OPERATION, version=6.16.0)
at makeError (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/utils/errors.ts:698:21)
at assert (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/utils/errors.ts:719:25)
at EnsResolver.getEnsAddress (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/ens-resolver.ts:545:9)
at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
at async EnsResolver.#getResolver (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/ens-resolver.ts:552:25)
at async EnsResolver.fromName (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/ens-resolver.ts:590:26)
at async JsonRpcProvider.getResolver (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/abstract-provider.ts:1193:16)
at async JsonRpcProvider.resolveName (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/abstract-provider.ts:1203:26)
at async Wallet.resolveName (/Users/owanate/Documents/Rootstock/hacktivator/ussd/node_modules/ethers/src.ts/providers/abstract-signer.ts:246:16) {
code: 'UNSUPPORTED_OPERATION',
operation: 'getEnsAddress',
info: { network: Network {} },
shortMessage: 'network does not support ENS'
}

Node.js v24.13.0

[jayzalani]

Hi, I have made note of the missing start-bridge script and added it to the package.json section as instructed.

To resolve the second error (ENS issue), please note that you have to first deploy the smart contract using:

npx hardhat ignition deploy --network rskTestnet ignition/modules/InclusiveDeFi.ts

Then copy the deployed contract address from the output and replace YOUR_DEPLOYED_CONTRACT_ADDRESS in index.ts with your actual 0x... address before running npm run start-bridge.

The ENS error occurs because ethers.js sees the placeholder text instead of a real address and tries to resolve it as an ENS name, which Rootstock does not support.

[owans]

Briefly explain why the use of Africa's Talking

[owans]

Kindly update the title here as well

[jayzalani]

@owans Hi, I’ve made the requested updates and pushed the latest changes to the PR. When you have time, could you please take another look? Thanks a lot!

[owans]

LGTM!

Dear @jai,

Congratulations, I'm pleased to inform you that your pull request for the USSD-Based Decentralized Finance System on Rootstock has been approved and merged into the Docs.

You will receive the follow up message from the team.

Thank you for your valuable contribution to the Rootstock ecosystem!