diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index b927beb8..bdad9a51 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -35,6 +35,17 @@ This section will cover the theoretical aspects and foundational concepts releva * **Integrations guides:** These will be part of the "Developers" section, detailing how to integrate the product with other systems. * **User guides:** These belong under the "Concept" section as they explain how to use the product rather than integrate with it. +### Quick Starts vs Use Cases (avoid duplicate maintenance) + +Some starter kits appear in **Developers → Quick Starts** and also have a **Use Cases** guide (for example Collective DAO). Follow these rules so install instructions do not diverge: + +1. **Canonical setup for a public repo:** Keep `git clone`, `.env` / `.env.example`, `npm install`, and `npm run dev` in the **GitHub README** for that repository. Treat it as the single source of truth for environment variables and versions. +2. **`/developers/quickstart/...` page:** Use a **short** quick start: goal in one or two sentences, prerequisites summary, link to the README for Setup, and a link to the **Use Cases** article for architecture, code maps, and checklists. Do not paste full env tables or multi-step install blocks if the README already has them. +3. **`/use-cases/...` page:** Focus on the **job to be done**, SDK usage, file mapping, risks, and FAQs. Link to the README (and optionally the quick start page) under **Getting Started** instead of duplicating install steps. +4. **Before adding content:** Search existing Quick Starts and the kit README. Prefer **one new paragraph plus links** over copying blocks into two portal locations. + +If you add a new starter kit to both areas, add a **Quick Starts** hub card and a **Use Cases** guide that references the same README pattern above. + ### Node Operators Section diff --git a/docs/01-concepts/fundamentals/stack/index.md b/docs/01-concepts/fundamentals/stack/index.md index 7387a67b..f76b00d6 100644 --- a/docs/01-concepts/fundamentals/stack/index.md +++ b/docs/01-concepts/fundamentals/stack/index.md @@ -17,7 +17,7 @@ Currently, the VM is executed by interpretation. In a future network upgrade, th * Performance improvement pipeline documented in numerous RSKIPs created by the Rootstock community * See the [Rootstock Improvement Proposals](https://github.com/rsksmart/RSKIPs). -![Rootstock Technology Stack - High Level](/img/concepts/rootstock-tech-stack.svg) +
@@ -41,4 +41,51 @@ The more hashing power they provide, the more secure the network is.

The Smart Bitcoin (rBTC) is the native currency in Rootstock and it is used to pay for the gas required for the execution of transactions. It is pegged 1:1 with Bitcoin, which means in Rootstock there are exactly 21M rBTC. A PowPeg allows the transfer of bitcoins from the Bitcoin blockchain to the Rootstock blockchain and vice-versa.

-
\ No newline at end of file + + +## The Stack + +When building BTCFi dApps, you interact with the **Rootstock Virtual Machine (RVM)**.Because the RVM is fully EVM-compatible, you can use industry-standard tools like **Remix, Hardhat, and Foundry** to manage Bitcoin-native assets. + +
+ {/* Application Layer */} +
+
APPLICATIONS
+
+
YIELD VAULTS
+
STAKING
+
AI AGENTS
+
+
+ {/* Tooling Layer */} +
+
DEVTOOL
+
+ REMIX • HARDHAT • FOUNDRY • OPENZEPPELIN • DAO SDK +
+
+ {/* Infrastructure Layer */} +
+
RIF SERVICES
+
+
RIF RELAY
+
RNS
+
FLYOVER
+
COLLECTIVE DAO
+
+
+ {/* Execution Layer */} +
+
EXECUTION
+
+
ROOTSTOCK VIRTUAL MACHINE (EVM-COMPATIBLE)
+
+
+ {/* Security Layer */} +
+
SECURITY
+
+
BITCOIN: MERGED MINING
+
+
+
\ No newline at end of file diff --git a/docs/01-concepts/rif-suite/rns/index.md b/docs/01-concepts/rif-suite/rns/index.md index 15b9cf93..57b75a53 100644 --- a/docs/01-concepts/rif-suite/rns/index.md +++ b/docs/01-concepts/rif-suite/rns/index.md @@ -1,7 +1,7 @@ --- sidebar_label: RNS sidebar_position: 400 -title: "RIF RNS: RIF Name Service" +title: "RIF Name Service (RNS)" tags: [rif, rns, rif-name-service, rsk, rootstock] description: "Information about the RIF Name Service, specs, how to use and integrate." --- @@ -10,7 +10,7 @@ RNS provides an architecture which enables the identification of blockchain addr -
+ -
+ + --> ## The stack diff --git a/docs/02-developers/04-quickstart/collective.md b/docs/02-developers/04-quickstart/collective.md new file mode 100644 index 00000000..5eed7ebf --- /dev/null +++ b/docs/02-developers/04-quickstart/collective.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 113 +sidebar_label: Collective DAO +title: Collective DAO Starter Kit +description: Run the Rootstock Collective sample dApp with Wagmi, RainbowKit, staking, proposals, and voting. Setup steps live in the GitHub README. +tags: [quickstart, collective-sdk, dao, governance, rootstock, wagmi, rif] +--- + +This quick start points to the [Rootstock Collective starter kit](https://github.com/rsksmart/rootstock-collective-starter-kit), a sample dApp that uses [`@rsksmart/collective-sdk`](https://www.npmjs.com/package/@rsksmart/collective-sdk) for staking RIF, listing proposals, and voting on Rootstock Mainnet or Testnet. + +## What you do here + +Follow the **Setup** section in the repo README: clone, copy `.env` from `.env.example`, set the variables it describes, install, and run `npm run dev`. That README is the **only** canonical place for install commands and environment keys so they stay in sync with the kit. + +## Prerequisites + +- Node.js 18+ +- A Reown (WalletConnect) project ID for the dApp (see README) +- Optional Rootstock RPC API key for higher rate limits (see README) +- A wallet on Rootstock (chain ID 30 or 31) with tRBTC for gas and RIF or stRIF as needed for flows you test + +## After the app runs + +For how SDK calls map to `src/` files, simulation before writes, governance UX edge cases, and a production checklist, use the use case guide: + +- [Build DAO voting and RIF utility with the Collective SDK](/use-cases/integrate-rif-economy/build-dao-voting-collective-sdk/) + +## References + +- [rootstock-collective-starter-kit on GitHub](https://github.com/rsksmart/rootstock-collective-starter-kit) +- [Collective SDK source](https://github.com/rsksmart/collective-sdk) +- [Rootstock Collective app](https://app.rootstockcollective.xyz/) diff --git a/docs/02-developers/04-quickstart/index.md b/docs/02-developers/04-quickstart/index.md index 08a1f154..654168a6 100644 --- a/docs/02-developers/04-quickstart/index.md +++ b/docs/02-developers/04-quickstart/index.md @@ -17,7 +17,8 @@ values={[ {label: 'Reown', value: 'reown'}, {label: 'On-chain data', value: 'data'}, {label: 'RPC API', value: 'rpc'}, -{label: 'Port to Rootstock', value: 'port-dapps'} +{label: 'Port to Rootstock', value: 'port-dapps'}, +{label: 'Governance', value: 'governance'} ]}> +
- - - - - - - - \ No newline at end of file diff --git a/docs/02-developers/index.md b/docs/02-developers/index.md index 270672d4..37be8452 100644 --- a/docs/02-developers/index.md +++ b/docs/02-developers/index.md @@ -26,6 +26,6 @@ This section enables developers getting started with the Rootstock blockchain. D | [Integration Guides](/developers/integrate/) | Deepen your knowledge with detailed guides and informative tutorials that cover various aspects of Rootstock development.| | [JSON-RPC](/developers/rpc-api/) | Test your dApps on testnet in minutes before deploying to mainnet using RPC API providers on Rootstock.| | [Libraries](/developers/libraries/) | Access essential tools and libraries to streamline your development process. | -| [Use Cases](/developers/use-cases/) | Explore Rootstock dApp use case guides and tutorials for building DeFi on Bitcoin, AI, and cross-chain solutions. | +| [Use Cases](/use-cases/) | Use case guides and tutorials for DeFi, onboarding, bridging, and automation on Rootstock. | diff --git a/docs/04-resources/04-tutorials/index.md b/docs/04-resources/04-tutorials/index.md index 5f124eb7..8e079a17 100644 --- a/docs/04-resources/04-tutorials/index.md +++ b/docs/04-resources/04-tutorials/index.md @@ -71,16 +71,16 @@ value="advanced, defi" title="Build an Omnichain Fungible Token (OFT) on Rootstock with Layerzero" subtitle="Cross chain" color="orange" -linkHref="/developers/use-cases/defi/rootstock-layerzero/" +linkHref="/use-cases/interoperability/rootstock-layerzero/" description="This guide demonstrates implementing cross-chain token transfers using OFT (Omnichain Fungible Token) between Rootstock Testnet and Ethereum Sepolia Testnet via LayerZero's OFT V2 protocol." />
Step 13: Continue filling in the other fields as amount and click on the Send button -Step 14: After finish the pegout transaction creation, click here to see how to see the steps to access to Bitcoin derived address in hardware wallet using [Electrum](/resources/guides/powpeg-app/advanced-operations#electrum-hardware-wallets) +Step 14: After finish the pegout transaction creation, click here to see how to see the steps to access to Bitcoin derived address in hardware wallet using [Electrum](/resources/guides/powpeg-app/advanced-operations) ---- diff --git a/docs/02-developers/09-use-cases/runes-rootstock/_category_.yml b/docs/04-resources/06-guides/runes-rootstock/_category_.yml similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/_category_.yml rename to docs/04-resources/06-guides/runes-rootstock/_category_.yml diff --git a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/Intro-to-airdrops.md b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/Intro-to-airdrops.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/Intro-to-airdrops.md rename to docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/Intro-to-airdrops.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/_category_.yml b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/_category_.yml similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/_category_.yml rename to docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/_category_.yml diff --git a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine.md b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine.md rename to docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md similarity index 97% rename from docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md rename to docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md index c43adb22..eff619d8 100644 --- a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md +++ b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/setup-airdrop.md @@ -53,7 +53,7 @@ This variable specifies the address of the Airdrop Manager smart contract. To en :::info[Info] -For detailed instructions on obtaining the Airdrop Manager address, please refer to the [Deployment](/developers/use-cases/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine/) section. +For detailed instructions on obtaining the Airdrop Manager address, please refer to the [Deployment](/resources/guides/runes-rootstock/airdrop-giveaway-machine/deploy-airdrop-machine/) section. ::: diff --git a/docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/template-repository.md b/docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/template-repository.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/airdrop-giveaway-machine/template-repository.md rename to docs/04-resources/06-guides/runes-rootstock/airdrop-giveaway-machine/template-repository.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/Intro-runes.md b/docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/Intro-runes.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/Intro-runes.md rename to docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/Intro-runes.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/_category_.yml b/docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/_category_.yml similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/_category_.yml rename to docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/_category_.yml diff --git a/docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-contracts.md b/docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-contracts.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-contracts.md rename to docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-contracts.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-deployment.md b/docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-deployment.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-deployment.md rename to docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-deployment.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-setup.md b/docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-setup.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/build-mockbridge-contract/runes-setup.md rename to docs/04-resources/06-guides/runes-rootstock/build-mockbridge-contract/runes-setup.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/governance-dashboard.md b/docs/04-resources/06-guides/runes-rootstock/governance-dashboard.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/governance-dashboard.md rename to docs/04-resources/06-guides/runes-rootstock/governance-dashboard.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/mock-contract-walthrough.md b/docs/04-resources/06-guides/runes-rootstock/mock-contract-walthrough.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/mock-contract-walthrough.md rename to docs/04-resources/06-guides/runes-rootstock/mock-contract-walthrough.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/overview.md b/docs/04-resources/06-guides/runes-rootstock/overview.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/overview.md rename to docs/04-resources/06-guides/runes-rootstock/overview.md diff --git a/docs/02-developers/09-use-cases/runes-rootstock/runes-setup.md b/docs/04-resources/06-guides/runes-rootstock/runes-setup.md similarity index 100% rename from docs/02-developers/09-use-cases/runes-rootstock/runes-setup.md rename to docs/04-resources/06-guides/runes-rootstock/runes-setup.md diff --git a/docs/05-dev-tools/cross-chain-bridges/index.md b/docs/05-dev-tools/cross-chain-bridges/index.md index 0d624873..17a48915 100644 --- a/docs/05-dev-tools/cross-chain-bridges/index.md +++ b/docs/05-dev-tools/cross-chain-bridges/index.md @@ -58,7 +58,7 @@ Imagine different islands, each with its own unique economy and currency. To tra subtitle="cross-chain" color="green" description="LayerZero, a cross-chain messaging protocol enables the seamless movement of Bitcoin-backed assets from Rootstock to other blockchains, allowing developers to build omnichain applications (OApps) that interact across multiple chains as if they were one." - linkHref="/developers/use-cases/defi/rootstock-layerzero/" + linkHref="/use-cases/interoperability/rootstock-layerzero/" linkTitle="Start Bridging" /> \ No newline at end of file diff --git a/docs/05-dev-tools/cross-chain-bridges/layerzero.md b/docs/05-dev-tools/cross-chain-bridges/layerzero.md index ffb66026..1b875335 100644 --- a/docs/05-dev-tools/cross-chain-bridges/layerzero.md +++ b/docs/05-dev-tools/cross-chain-bridges/layerzero.md @@ -9,5 +9,5 @@ tags: [Layerzero, bridges, developer tools, rsk, testnet, rootstock, ethereum, d Rootstock now integrates with LayerZero, a cross-chain messaging protocol. This integration enables the seamless movement of Bitcoin-backed assets from Rootstock to other blockchains, allowing developers to build omnichain applications (OApps) that interact across multiple chains as if they were one. Users can now move their Bitcoin across different DeFi ecosystems without complicated bridges, high fees, or slow transactions. ## Resources -- [How Build Omnichain Fungible Token (OFTs) on Rootstock with Layerzero](/developers/use-cases/defi/rootstock-layerzero/). +- [How Build Omnichain Fungible Token (OFTs) on Rootstock with Layerzero](/use-cases/interoperability/rootstock-layerzero/). - [Deployed Endpoints, Message Libraries, and Executors](https://docs.layerzero.network/v2/deployments/deployed-contracts) \ No newline at end of file diff --git a/docs/05-dev-tools/index.md b/docs/05-dev-tools/index.md index 0460fdcf..cec8e999 100644 --- a/docs/05-dev-tools/index.md +++ b/docs/05-dev-tools/index.md @@ -87,7 +87,7 @@ description: "Explore a curated selection of smart contract development tools an title="Agents" subtitle="Dev Tools" color="orange" - linkHref="/developers/use-cases/ai/ai-agent-rootstock/" + linkHref="/use-cases/ai-automation/ai-agent-rootstock/" linkTitle="Create AI Agent" description="This guide demonstrates how to build a lightweight dApp that connects a conversational AI agent to the Rootstock testnet, allowing users to perform DeFi actions like checking token balances and sending tRBTC simply by chatting." /> @@ -690,7 +690,7 @@ description: "Explore a curated selection of smart contract development tools an title="Layerzero" subtitle="Cross Chain Bridges" color="orange" - linkHref="/developers/use-cases/defi/rootstock-layerzero/" + linkHref="/use-cases/interoperability/rootstock-layerzero/" linkTitle="Build Cross Chain dApps" description="LayerZero, a cross-chain messaging protocol enables the seamless movement of Bitcoin-backed assets from Rootstock to other blockchains, allowing developers to build omnichain applications (OApps) that interact across multiple chains as if they were one." /> @@ -726,7 +726,7 @@ description: "Explore a curated selection of smart contract development tools an title="Para" subtitle="wallets" color="orange" - linkHref="/developers/quickstart/para/" + linkHref="/use-cases/onboarding-ux/para/" linkTitle="Use Para" description="Para is a modern wallet infrastructure for fintech and crypto applications. It provides a comprehensive wallet and authentication suite for crypto developers and apps." /> diff --git a/docs/06-use-cases/ai-automation/_category_.yml b/docs/06-use-cases/ai-automation/_category_.yml new file mode 100644 index 00000000..a5dda9b1 --- /dev/null +++ b/docs/06-use-cases/ai-automation/_category_.yml @@ -0,0 +1,5 @@ +label: "Automation and AI" +position: 4 +link: + type: doc + id: use-cases/ai-automation/index \ No newline at end of file diff --git a/docs/06-use-cases/ai-automation/_integrate-rootstock-sdk.md b/docs/06-use-cases/ai-automation/_integrate-rootstock-sdk.md new file mode 100644 index 00000000..2ddf4738 --- /dev/null +++ b/docs/06-use-cases/ai-automation/_integrate-rootstock-sdk.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 3 +title: "Integrate Rootstock SDK logic into automated workflows" +sidebar_label: Integrating SDK logic +description: "Use Rootstock SDK layers so automation can read chain state and submit guarded transactions." +tags: [ai, agents, mcp, sdk, btcfi, automation, x402] +--- + +Automation that reacts to markets or user chat needs fresh chain data and a safe path to submit transactions. The Rootstock SDK splits that work into a Web3 core layer, shared helpers, and domain modules. This tutorial explains how to wire those pieces so a workflow can read balances and vault state, then execute writes only inside the limits you configure. + +## Architecture Overview +The Rootstock SDK uses a three-layer pattern to separate blockchain logic from business logic: + +* Web3 Core Layer (@rskSmart/w3layer): This independent package handles low-level interactions like providers and JSON-RPC methods. + +* Shared Base Functions (@rskSmart/sdk-base): This repository encapsulates cross-SDK utilities like error management and logging. + +* Module Specific Functions: These contain business logic for domains like Collective DAO or Yield Vaults. + +## The Agentic Architecture: Eyes and Hands +To act autonomously, an AI agent requires two things: +1. **Context (The Eyes):** Real-time data about balances, vault APYs, and contract states. +2. **Execution (The Hands):** The ability to sign and broadcast transactions to the Rootstock Virtual Machine (RVM). + +## Prerequisites +You must install the following packages to begin the integration: + +* Node.js v18 or higher. +* Access to a Rootstock RPC node. +* The `@rskSmart/w3layer` and `@rskSmart/collective` SDK modules. + +## Providing Chain Context to the Agent +An AI agent needs data to perform its role. You use the SDK "Read" functions to fetch this context. The following flow demonstrates how an agent requests account information through the SDK module and the Contract Registry. + +### Implementation: Reading Balances +The agent calls a function to check its current rBTC holdings before it suggests a trade or a vote. + +```ts +// Initialize the Web3 Core Layer to interact with the chain +const core = new Web3CoreLayer(config); + +// Load the specific module for the agent's task +const collective = new CollectiveSDK(core); + +// Request the balance for a specific address +// The SDK fetches contract addresses and ABIs from the registry automatically +const balance = await collective.readBalance(agentAddress); +``` + +The LLM receives this balance as part of its prompt context. The agent now possesses the data required to decide on the next action. + +## Executing Autonomous Actions +When the agent decides to act, it follows the SDK "Write" sequence. This process involves transaction simulation and signature requests to ensure safety. + +### Implementation: Executing a Write Function +The agent initiates a transaction, such as staking rBTC or voting on a proposal. The SDK simulates the transaction first to validate the result. + +```ts +// Define the parameters for the write function +const stakeParams = { amount: parseEther("0.1") }; + +// The SDK simulates the TX via the Web3 Core Layer +// This step validates the transaction before the user signs it +const txHash = await collective.writeContract("stakeRif", stakeParams, signer); + +// Check for confirmations to ensure the action is finalized +const status = await core.checkConfirmations(txHash); +``` + +Ensure to implement spend permissions if the agent acts autonomously. These permissions limit the amount of rBTC an agent can move without a new manual signature. + +## Next steps + +* [DAO voting with the Collective SDK](/use-cases/integrate-rif-economy/build-dao-voting-collective-sdk/) +* [Generate Yield overview](/use-cases/btcfi-finance-yield/) (includes [USDRIF Vaults SDK walkthrough](/use-cases/btcfi-finance-yield/yield-vaults-sdk/)) +* [Integrating x402 payments with Rootstock](/resources/tutorials/integrate-x402/) \ No newline at end of file diff --git a/docs/02-developers/09-use-cases/ai/ai-agent-rootstock.md b/docs/06-use-cases/ai-automation/ai-agent-rootstock.md similarity index 99% rename from docs/02-developers/09-use-cases/ai/ai-agent-rootstock.md rename to docs/06-use-cases/ai-automation/ai-agent-rootstock.md index 4aaf04c8..625b1fc2 100644 --- a/docs/02-developers/09-use-cases/ai/ai-agent-rootstock.md +++ b/docs/06-use-cases/ai-automation/ai-agent-rootstock.md @@ -1,6 +1,6 @@ --- -sidebar_label: AI Agents -sidebar_position: 200 +sidebar_label: Conversational AI Agents +sidebar_position: 205 title: Conversational AI Agent with Blockchain Actions on Rootstock tags: [rsk, rootstock, ai agents, ai] description: "This tutorial demonstrates how to build a lightweight dApp that connects a conversational AI agent to the Rootstock testnet, allowing users to perform DeFi actions like checking token balances and sending tRBTC simply by chatting." diff --git a/docs/06-use-cases/ai-automation/index.md b/docs/06-use-cases/ai-automation/index.md new file mode 100644 index 00000000..71512262 --- /dev/null +++ b/docs/06-use-cases/ai-automation/index.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 1 +title: Automation and AI +sidebar_label: Overview +description: "Connect automation and AI tooling to Rootstock for read and write flows with clear guardrails." +tags: [ai, mcp, agents, autonomous-finance, emerging-tech, fundamentals] +--- + +This section is for builders who want **read access** to chain data and **limited writes** from automated workflows. MCP servers, SDK modules, and explicit permission scopes support that pattern. They do not replace a threat model: you still decide what an agent may spend, to which addresses, and for how long. + + + +## Core pillars + +| Pillar | Description | Primary tool | +| :--- | :--- | :--- | +| **Connectivity** | Expose chain reads and scoped actions to MCP clients. | [Rootstock MCP Server](https://github.com/rsksmart/rootstock-mcp-server) | +| **SDK** | Read state and submit guarded transactions from your stack. | [Rootstock SDK base](https://github.com/rsksmart/sdk-base) | +| **Indexing** | Historical and aggregate data for dashboards and automation. | [The Graph on Rootstock](/dev-tools/data/thegraph/) | + +## Key concepts + +### 1. Model Context Protocol (MCP) + +MCP connects clients to tools and data sources. The **Rootstock MCP Server** can read balances, contract state, and gas estimates so responses reflect current chain data. Writes still need user-approved keys or policies you control. + +### 2. Spend permissions and session keys + +Automation should not hold an unrestricted private key. Use spend permissions or session scopes that limit amount, destination, and duration for any transfer a model can request. + +### 3. Rules-based actions + +With clear rules and permissions, a workflow can react to on-chain signals (for example vault or price conditions). You own the policy, monitoring, and rollback path. No guide here guarantees returns or strategy performance. + +## Tools + +* **Rootstock MCP Server:** Exposes chain reads and safe actions to MCP clients. +* **LangChain / Eliza:** Orchestration frameworks you can point at Rootstock RPC and wallets. +* **Safe SDK:** Multi-sig and policy-based execution for high-value automation. + +## Implementation guides + +Published guides in this section are listed below. + +import DocCardList from '@theme/DocCardList'; + + \ No newline at end of file diff --git a/docs/02-developers/09-use-cases/ai/mcp-rootstock.md b/docs/06-use-cases/ai-automation/mcp-rootstock.md similarity index 98% rename from docs/02-developers/09-use-cases/ai/mcp-rootstock.md rename to docs/06-use-cases/ai-automation/mcp-rootstock.md index 8c6782c6..1a9227c6 100644 --- a/docs/02-developers/09-use-cases/ai/mcp-rootstock.md +++ b/docs/06-use-cases/ai-automation/mcp-rootstock.md @@ -1,7 +1,7 @@ --- -sidebar_label: Model Context Protocols (MCP) | Overview +sidebar_label: Introduction to MCPs sidebar_position: 200 -title: Understanding Model Context Protocols (MCPs) +title: Introducing Model Context Protocols (MCPs) on Rootstock tags: [rsk, rootstock, mcp, ai agents, ai] description: "This section demonstrates how to interact with the Rootstock blockchain to build and deploy innovative AI-enabled dApps." --- diff --git a/docs/06-use-cases/btcfi-finance-yield/_automate-yield-vault.md b/docs/06-use-cases/btcfi-finance-yield/_automate-yield-vault.md new file mode 100644 index 00000000..6000b0b2 --- /dev/null +++ b/docs/06-use-cases/btcfi-finance-yield/_automate-yield-vault.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 3 +sidebar_label: Building Automated Yield Vaults +title: Building Automated Yield Vaults +description: "Learn to build and manage automated yield strategies on Bitcoin using the Rootstock Vaults SDK." +tags: [btcfi, automation, vaults, sdk, rbtc, dev-tutorial] +--- + +Automated yield vaults execute predefined strategies to optimize returns for depositors. The Rootstock Vaults SDK simplifies the development of these vaults by providing standardized interfaces for capital movement. This tutorial covers the logic required to build a vault that rebalances assets across multiple protocols. + +## The Automation Layer + +Automated vaults reduce manual intervention by programmatically shifting funds. You use the `@rskSmart/vaults` module to monitor vault performance and trigger rebalancing events based on on-chain data. + +[cite_start]The SDK interacts with the Web3 Core Layer to ensure every automated action is simulated before execution [cite: 908-909]. This verification step is critical because failing transactions on the mainnet consume gas without providing a result. + +## Technical Architecture for Automation + +The Rootstock SDK follows a layered pattern to maintain scalability. The Web3 Core Layer manages the low-level blockchain logic, while the Vaults module handles high-level business functions [cite: 908-909]. + +1. **Web3 Core Layer:** It provides the JSON-RPC methods to query the state of the blockchain. +2. **Shared Base Functions:** These encapsulate common utilities like error handling for the automation loop. +3. **Module Specific Functions:** These execute the rebalancing logic, such as moving rBTC from one yield protocol to another. + + + +## Implementing the Automation Loop + +You must create a loop that checks the current strategy's efficiency. The agent uses the "Read" function sequence to fetch current yields from the Contract Registry [cite: 908-909]. + +### Querying Strategy Performance + +The vault must know the current Annual Percentage Yield (APY) of its underlying strategies. + +```ts +// Initialize the Vaults SDK with your configuration +const vaults = new VaultsSDK(core); + +// Fetch the performance data for your primary strategy +// The registry provides the ABI and address for the strategy contract +const currentApy = await vaults.getVaultApy("rBTC-Alpha-Strategy"); +``` + +## Executing the Rebalance + +If a new strategy offers a higher return, you trigger a rebalance. This involves the "Write" function sequence, which requires a wallet client or signer to authorize the movement of funds [cite: 908-909]. + +### Triggering the Asset Shift + +You must handle the complexity of protocol permissions. Most yield protocols require an approval step before the vault can move assets. + +```ts +// Define the rebalancing parameters +const rebalanceParams = { targetProtocol: "rBTC-Beta-Strategy", amount: totalBalance }; + +// Simulate the rebalance transaction to check for potential errors +// The signer provides the authorization for the execution +const txHash = await vaults.writeContract("rebalance", rebalanceParams, signer); + +// Monitor the confirmation status to verify the funds reached the target +const finalStatus = await core.checkConfirmations(txHash); +``` + +## Functional Flow in the Rootstock Stack + +Automation sits at the top of the stack, leveraging the RVM for logic and Bitcoin for settlement security. + +
+
+
OUTCOME
+
+
AUTOMATED YIELD
+
STRATEGY OPTIMIZATION
+
+
+ +
+
DEVELOP
+
+ ROOTSTOCK VAULTS SDK • HARDHAT +
+
+ +
+
UTILITY
+
+
WEB3 CORE LAYER
+
CONTRACT REGISTRY
+
+
+ +
+
LOGIC
+
+
ROOTSTOCK VIRTUAL MACHINE (EVM-COMPATIBLE)
+
+
+ +
+
SETTLE
+
+
BITCOIN: SECURE SETTLEMENT LAYER
+
+
+
+ +## Next Steps + +Automating your vault is only the beginning. You can now integrate more complex logic: + +* [Automation and AI on Rootstock](/use-cases/ai-automation/) +* [RIF economy and governance](/use-cases/integrate-rif-economy/) +* [Rootstock Explorer](/dev-tools/explorers/rootstock/) \ No newline at end of file diff --git a/docs/06-use-cases/btcfi-finance-yield/_category_.yml b/docs/06-use-cases/btcfi-finance-yield/_category_.yml new file mode 100644 index 00000000..891edf20 --- /dev/null +++ b/docs/06-use-cases/btcfi-finance-yield/_category_.yml @@ -0,0 +1,5 @@ +label: "Generate Yield" +position: 2 +link: + type: doc + id: use-cases/btcfi-finance-yield/index \ No newline at end of file diff --git a/docs/06-use-cases/btcfi-finance-yield/index.md b/docs/06-use-cases/btcfi-finance-yield/index.md new file mode 100644 index 00000000..cb39f58d --- /dev/null +++ b/docs/06-use-cases/btcfi-finance-yield/index.md @@ -0,0 +1,111 @@ +--- +sidebar_position: 2 +title: Generate Yield +sidebar_label: Overview +description: "BTCFi on Rootstock: rBTC, vaults, and stable units of account for builders." +--- + +BTCFi on Rootstock means lending, borrowing, yield, and liquidity apps that use rBTC and other assets on an EVM-compatible chain anchored to Bitcoin. + +This section is for **builders** who implement strategies and vault integrations. **Who may use a live vault product** depends on the program, jurisdiction, and whether access is institutional, retail, or partner-only. + + + +## Core pillars + +| Pillar | Description | Where to go | +| :--- | :--- | :--- | +| **Vaults SDK** | ERC-4626 style flows for the USDRIF vault on Rootstock. | [Integrate USDRIF Vault](/use-cases/btcfi-finance-yield/yield-vaults-sdk/). Install and API details stay in the [Vaults SDK README](https://github.com/rsksmart/vaults-sdk). | +| **Stable units of account** | USD-pegged assets such as USDRIF for pricing and debt. | [RIF On Chain](https://rifonchain.com/) | +| **Liquidity and credit** | Lending and borrowing markets on top of rBTC and stable assets. | Protocol documentation for the venues you integrate (for example [Tropykus](https://app.tropykus.com/), [Money on Chain](https://moneyonchain.com/)) | + + +## Key Concepts + +### 1. rBTC (Bitcoin-pegged gas and collateral) + +rBTC is the native asset on Rootstock. It is pegged 1:1 with BTC through the PowPeg. When you [peg in](/resources/guides/powpeg-app/pegin/), BTC is locked on Bitcoin and rBTC is available on Rootstock. You pay gas in rBTC and use it as collateral in DeFi protocols. + +### 2. USDRIF and stablecoins + +Bitcoin is volatile, so many apps need a stable unit of account. **USDRIF** is a decentralized, USD-pegged asset with Bitcoin-backed collateral. Read the issuer and pool documentation before you integrate it in production. + +### 3. Liquid staking (LSTs) + +Some protocols issue receipt tokens when you stake rBTC (for example `st-rBTC`). Behavior, rewards, and risk depend on each protocol. Read the contract and liquidation rules before you treat an LST as collateral elsewhere. + +## Tools developers use + +* **Vaults SDK:** Yield and vault UX on Rootstock. +* **Money on Chain:** Bitcoin-backed stablecoins and leverage products. +* **Tropykus:** Lending and borrowing markets. + +## Implementation guides + +When you publish a guide in this folder (remove the leading `_` from the filename), it appears as a card below. Until then this section stays empty. + +import DocCardList from '@theme/DocCardList'; + + \ No newline at end of file diff --git a/docs/06-use-cases/btcfi-finance-yield/yield-vaults-sdk.md b/docs/06-use-cases/btcfi-finance-yield/yield-vaults-sdk.md new file mode 100644 index 00000000..842e761d --- /dev/null +++ b/docs/06-use-cases/btcfi-finance-yield/yield-vaults-sdk.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 4 +sidebar_label: Integrate USDRIF Vault +title: "Integrate Your First USDRIF Vault on Rootstock" +description: "Use the Rootstock Vaults SDK and viem to read vault state, approve USDRIF, and deposit with slippage protection." +tags: [btcfi, yield, vault, sdk, usdrif, dev-tutorial] +--- + +The [Vaults SDK](https://github.com/rsksmart/vaults-sdk) is a TypeScript client for the **USDRIF yield vault** on Rootstock. You can deposit USDRIF, hold shares, and redeem or withdraw back to USDRIF using the Vault SDK. Refer to the [repository README](https://github.com/rsksmart/vaults-sdk) as the source of truth for installation steps, and contract addresses. + +## What you are integrating + +You connect a **viem** `WalletClient` and optional `PublicClient` to the SDK. **Read** calls go through `sdk.vault` (vault metrics, strategies, user position, previews, allowance). **Write** calls go through `sdk.write` (approve USDRIF, deposit, withdraw, redeem, including slippage-protected variants). + +You still pay transaction fees in **rBTC**. Deposits and withdrawals use **USDRIF** (and the protocol may surface **USDT0** balances where relevant). Do not assume **estimated APY** or strategy names are guarantees. They are on-chain views that can change with market conditions and allocator updates. + +## Prerequisites + +* Node.js and a package manager compatible with the README install path. +* A wallet funded with **rBTC** on [Rootstock Testnet](https://explorer.testnet.rootstock.io/) (chain ID `31`) for gas. Mainnet (chain ID `30`) support in the SDK is **coming soon** per the README. +* **USDRIF** in that wallet for testnet. +* An RPC URL you are allowed to use in production (the README examples use Rootstock RPC with an API key). + +## Initialize the SDK + +Pass **chain ID** `31` for testnet or `30` for mainnet when it is available. Optional overrides include `rpcUrl`, `vaultAddress`, `usdrifAddress`, and `usdt0Address` if you run against custom deployments. + +```ts +import { VaultsSDK } from "@rsksmart/vaults-sdk" + +// 31 = Rootstock Testnet, 30 = Mainnet (when supported) +const sdk = new VaultsSDK({ chainId: 31 }) +``` + +:::info[Contract Addresses] + +Testnet contract addresses and the latest options are listed in the [Vaults SDK README](https://github.com/rsksmart/vaults-sdk). +::: + +## Read vault state + +Call `getVaultInfo()` for aggregate metrics: total assets, total shares, estimated APY, price per share, buffer ratio, and buffer balance. Call `getStrategies()` for per-strategy allocation and APY. Use `getUserBalance(address)` for shares, USDRIF equivalent, wallet balances, and max withdraw or redeem amounts. + +```ts +const vaultInfo = await sdk.vault.getVaultInfo() +console.log("Total assets:", vaultInfo.totalAssets.formatted, "USDRIF") +console.log("Estimated APY:", vaultInfo.estimatedApy.toFixed(2), "%") + +const { strategies } = await sdk.vault.getStrategies() +``` + +## Deposit flow (allowance, then write) + +Writes require a **viem** `WalletClient` on the correct chain. The README recommends **slippage-protected** deposit and withdraw helpers. A typical deposit checks allowance, approves if needed, waits for the approval receipt, then calls `depositWithSlippage`. + +```ts +import { parseEther } from "viem" + +// Configure walletClient and publicClient per your app (see README full example). +const depositAmount = parseEther("10") +const { isEnough } = await sdk.vault.getAllowance(userAddress, depositAmount) + +// If !isEnough, call approveUSDRIF and wait for the receipt before depositing. +// const approveTx = await sdk.write.approveUSDRIF(walletClient, depositAmount) +// await publicClient.waitForTransactionReceipt({ hash: approveTx.hash }) + +// const depositTx = await sdk.write.depositWithSlippage(walletClient, depositAmount, 0.5) +// await publicClient.waitForTransactionReceipt({ hash: depositTx.hash }) +``` + +The [README full example](https://github.com/rsksmart/vaults-sdk) wires `getAllowance`, `approveUSDRIF`, `depositWithSlippage`, and receipt waiting in one script. Use `previewDeposit`, `previewWithdraw`, and `previewRedeem` before you commit to amounts in UI copy. + +## Withdraw and redeem + +`withdraw`, `withdrawWithSlippage`, `redeem`, and the preview methods mirror the deposit pattern. Optional `receiver` and `owner` parameters follow the README. Always treat max withdraw and max redeem from `getUserBalance` as the upper bound for what the vault will allow for that user at that block. + +## Next steps + +* Copy the **Types** exports from the README when you type your integration layer. +* Re-read allocator and issuer documentation for **USDRIF** before you expose APY or TVL to end users. +* [Automation and AI on Rootstock](/use-cases/ai-automation/) +* [RIF economy and governance](/use-cases/integrate-rif-economy/) +* [Rootstock Explorer](/dev-tools/explorers/rootstock/) diff --git a/docs/06-use-cases/index.md b/docs/06-use-cases/index.md new file mode 100644 index 00000000..07cc01d1 --- /dev/null +++ b/docs/06-use-cases/index.md @@ -0,0 +1,144 @@ +--- +sidebar_position: 1 +title: Use Cases +sidebar_label: Overview +tags: [rsk, rootstock, use cases, solutions, guides, tutorials, institutions, users, developers] +description: "Implementation guides for building and integrating on Rootstock." +--- + +The **Use Cases** hub groups tasks you can ship: onboarding, bridging, automation, governance, and payments. Each published guide states prerequisites, flags risks where they matter, and walks through concrete steps for integration on Rootstock. + +:::note[Expand the library] + +If you want a new guide in this hub, use the links below. + +* Request a use case article using the Request Article on the right navigation options on this page. +* [**Submit on Idea on the Hacktivator Marketplace**](https://hacktivator-marketplace.rootstock.io/) +* [**Rootstock Discord**](https://discord.gg/rootstock) + +::: + +## Explore by use case + +Use the filters to narrow by goal. Links go only to **published** guides or section overviews. + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/06-use-cases/integrate-rif-economy/_category_.yml b/docs/06-use-cases/integrate-rif-economy/_category_.yml new file mode 100644 index 00000000..8141f014 --- /dev/null +++ b/docs/06-use-cases/integrate-rif-economy/_category_.yml @@ -0,0 +1,5 @@ +label: "RIF economy and governance" +position: 6 +link: + type: doc + id: use-cases/integrate-rif-economy/index \ No newline at end of file diff --git a/docs/06-use-cases/integrate-rif-economy/build-dao-voting-collective-sdk.md b/docs/06-use-cases/integrate-rif-economy/build-dao-voting-collective-sdk.md new file mode 100644 index 00000000..e68b0006 --- /dev/null +++ b/docs/06-use-cases/integrate-rif-economy/build-dao-voting-collective-sdk.md @@ -0,0 +1,323 @@ +--- +title: Build DAO Voting and RIF Utility on Rootstock with the Collective SDK +description: Learn how to build Rootstock governance dApps with the Collective SDK. Use the starter kit to stake RIF, fetch proposals, simulate writes, and cast votes safely. +slug: /use-cases/integrate-rif-economy/build-dao-voting-collective-sdk +sidebar_label: DAO Voting with Collective SDK +sidebar_position: 3 +tags: + - governance + - dao + - collective-sdk + - rif + - rootstock +keywords: + - Rootstock Collective SDK + - on-chain voting Rootstock + - DAO voting + - RIF staking +--- + +This guide is written for developers who want to move from reading SDK docs to building production dApps with staking, governance, and RIF utility. + +## Why Build Governance dApps? + +Governance dApps fail when developers cannot connect business goals to chain actions. The Collective SDK solves that gap for Rootstock by exposing staking, proposals, backing, and holdings in one TypeScript package. You can ship participation flows fast, then expand into richer use cases. + +For this guide, the target outcome is practical. A developer should be able to open a starter kit, connect a wallet, stake RIF, read active proposals, and cast a vote with simulation before write. + +This is the core bridge between RIF utility and DAO activity. + +## What the Kit Covers + +The starter kit is a working reference app. It covers governance participation and keeps complexity low. + +Implemented now: + +- Connect wallet with Wagmi and RainbowKit. +- Initialize `CollectiveSDK` for Rootstock Mainnet or Testnet. +- Stake and unstake RIF. +- Fetch and display proposals. +- Vote with simulation before submit. + +Not implemented in the sample UI: + +- Proposal creation UI. +- Backing module UI. +- Rewards claim UI. +- Vault-specific flows. + +Those are ideal "build next" paths for teams that need custom business logic. + +## Getting Started + +- **Setup:** Clone, environment variables, `npm install`, and `npm run dev` live in the [rootstock-collective-starter-kit README](https://github.com/rsksmart/rootstock-collective-starter-kit) (Setup). The Dev Portal does not copy those steps here. When the kit changes, update the README once and both the [quick start](/developers/quickstart/collective/) and this guide stay accurate. + +- **Quick start:** Use [Collective DAO starter kit](/developers/quickstart/collective/) for links to the repo and a minimal run checklist. + +- **Deep dive:** Continue with [About the SDK](#about-the-sdk) for how Collective SDK methods map to files in the kit, simulation, FAQs, and a production checklist. + +## About the SDK + +The package is [`@rsksmart/collective-sdk`](https://www.npmjs.com/package/@rsksmart/collective-sdk). It exposes modules you can compose by use case. + +- `sdk.staking` for RIF to stRIF flows and voting power setup. +- `sdk.proposals` for reading proposals and casting votes. +- `sdk.backing` for builder allocation workflows. +- `sdk.holdings` for balances, voting power, and rewards. + +The [starter kit](https://github.com/rsksmart/rootstock-collective-starter-kit) demonstrates the first two modules directly in UI components. It also keeps contract addresses explicit in one file so teams can manage deployments safely. + +```ts +// /src/constants/contracts.ts +// Override Collective contract addresses per Rootstock chain. +export const COLLECTIVE_CONTRACT_ADDRESSES = { + 31: { + governor: "0x25b7eb94f76cc682a402da980e6599478a596379", + treasury: "0xc4dacee263b0d1f2a09006dbc0170a4fda861b68", + backersManager: "0xd520cb42c46115762c02e4340646c2051ca3406d", + builderRegistry: "0x5fc1dd934ef2e6b5c4a433a3ec0a1326834b0f42", + RIF: "0x19f64674D8a5b4e652319F5e239EFd3bc969a1FE", + stRIF: "0xe7039717c51c44652fb47be1794884a82634f08f", + USDRIF: "0x8dbf326e12a9fF37ED6DDF75adA548C2640A6482", + }, +} as const +``` + +## Core Implementation Flow + +This section maps method calls to files within the kit so developers can navigate quickly. + +### 1) Initialize SDK from wallet chain + +Use the connected wallet chain. Do not hardcode one network in the hook. + +```ts +// /src/hooks/useCollective.ts +// Create CollectiveSDK for chain 30 or 31 with explicit address overrides. +const sdk = new CollectiveSDK({ + chainId, + rpcUrl, + contractAddresses, +}) +``` + +What it does: +- File: `src/hooks/useCollective.ts` +- Method: `new CollectiveSDK({ chainId, rpcUrl, contractAddresses })` +- Guardrails: return `isReady: false` when wallet is disconnected or chain is not Rootstock. + +### 2) Stake RIF and mint voting power + +Stake is a two-step flow when allowance is missing. + +```ts +// /src/components/dao/StakingCard.tsx +// Check allowance before staking. +const info = await sdk.staking.getStakingInfo(address) +const needsApprove = !info.hasAllowance(value) + +// Simulate and approve only when required. +if (needsApprove) { + await simulateApproveRIF(publicClient, address, addresses, value) + const approveTx = await sdk.staking.approveRIF(walletClient, value) + await approveTx.wait() +} + +// Simulate and execute stake. +await simulateStakeRIF(publicClient, address, addresses, value, address) +const stakeTx = await sdk.staking.stakeRIF(walletClient, value, address) +await stakeTx.wait() +``` + +What it does: +- File: `src/components/dao/StakingCard.tsx` +- Methods: `getStakingInfo`, `approveRIF`, `stakeRIF`, `unstakeRIF` +- UX detail: stake progress timeline in component state. + +### 3) Read active proposals + +The list view fetches proposals and renders proposal state plus votes. + +```ts +// /src/components/dao/ProposalList.tsx +// Fetch proposal list with an explicit limit. +const result = await sdk.proposals.getProposals({ limit: 20 }) +``` + +What it does: + +- File: `src/components/dao/ProposalList.tsx` +- Method: `sdk.proposals.getProposals({ limit: 20 })` +- Empty state message clarifies that proposal creation is outside current sample scope. + +### 4) Cast vote with support option + +Vote uses `VoteSupport` enum and sends the wallet signature. + +```ts +// /src/components/dao/VoteButton.tsx +// Simulate first, then cast vote. +await simulateCastVote(publicClient, address, addresses, proposalId, support) +const voteTx = await sdk.proposals.castVote(walletClient, proposalId, support) +await voteTx.wait() +``` + +What it does: + +- File: `src/components/dao/VoteButton.tsx` +- Method: `sdk.proposals.castVote(walletClient, proposalId, support)` +- Enum: `VoteSupport.For | VoteSupport.Against | VoteSupport.Abstain` + +## Simulation before Write is Required + +Write calls can fail for predictable reasons. The starter kit simulates every write and stops early on failure. + +Simulation helpers live in `src/lib/simulation.ts`. + +```ts +// /src/lib/simulation.ts +// Simulate vote call against Governor before sending transaction. +await publicClient.simulateContract({ + address: addresses.governor, + abi: governorCastVoteAbi, + functionName: "castVote", + args: [id, support], + account, +}) +``` + +This pattern protects users from avoidable gas spend and gives clear feedback for balance, allowance, and proposal-state issues. + +> Implement one additional flow, backing, rewards, or proposal creation. + +## Error Handling for Builders + +In your app, pair UI feedback with clear failure semantics, say what failed and why, not only a toast. + +In `src/lib/errors.ts`, insufficient voting power is handled with context: + +```ts +// /src/lib/errors.ts +// Explain VP snapshot behavior so users know why vote can fail after staking. +return `${current}Voting power is based on your stRIF at the proposal snapshot (start of voting period); new stakes apply from the next epoch. You need more than 0 stRIF to vote. 1 RIF staked = 1 voting power.` +``` + +This is important for governance UX. Users often assume staking now means voting now. Proposal snapshots can invalidate that expectation. + +## Production Checklist for Builders + +Before publishing your own Collective-based dApp: +- Confirm wallet chain updates trigger state refresh for balances and SDK flows. +- Verify RIF and stRIF addresses per chain in `constants/contracts.ts`. +- Keep simulation before all writes, including proposal creation if you add it. +- Show explorer links for every write result so users can verify on chain. +- Include RPC key fallback logic. Public nodes can rate limit in traffic spikes. +- Test insufficient VP and allowance failures intentionally. +- Test wallet reconnect and account switching. + +## Extend the Use Cases from this Base + +This section ties directly to RIF utility strategy. + +### Use case 1: Backing allocation dashboard + +Goal: let stRIF holders allocate support to builders and monitor returns. + +SDK paths: + +- `sdk.backing.getBuilders()` +- `sdk.backing.getBackedBuilders()` +- `sdk.backing.getAvailableForBacking()` + +Business impact: + +- Increases stickiness for stRIF holders. +- Turns governance participation into active ecosystem allocation. + +### Use case 2: Rewards cockpit for active backers + +Goal: show claimable balances and claim paths in one screen. + +SDK paths: + +- `sdk.holdings.getBalances()` +- `sdk.holdings.getUnclaimedRewards()` +- `sdk.holdings.claimRewards()` + +Business impact: + +- Makes reward flow visible, which increases recurring engagement. + +### Use case 3: Treasury operation builder + +Goal: create and track treasury-related governance proposals. + +SDK paths: + +- `sdk.proposals.createProposal()` +- `sdk.proposals.createTreasuryTransferProposal()` +- `sdk.proposals.getProposalDetails()` + +Business impact: + +- Expands from participation to DAO operations. + +## Frequently Asked Questions + +This FAQ is based on issues that may surface while implementing and testing the starter kit. + +### Why does the app not react when I switch networks in MetaMask? + +Your UI state can become stale if you do not invalidate queries on wallet events. The starter kit addresses this with wallet sync and query invalidation. Also verify your chain guard. `useCollective` returns not-ready state when chain is not Rootstock. + +### Why do I see tRBTC balance but no RIF balance? + +Native balance and ERC20 balance are separate reads. Verify the RIF token address for your chain in `constants/contracts.ts`. Also verify that token reads use the same connected chain. If token balance reads are undefined, inspect RPC and token contract availability for that chain. + +### Why does voting fail right after staking? + +Voting power is tied to proposal snapshot timing. New stakes may apply in a later epoch. The starter kit surfaces this via `getInsufficientVPDescription` in `src/lib/errors.ts`. + +### Why do I need simulation if the SDK already validates? + +Simulation catches contract reverts before signature and send. It reduces user friction and failed transactions. Keep it for all writes. + +### What wallet object should I pass to SDK write methods? + +Pass Wagmi `walletClient`. The SDK expects a signer-capable client for `approveRIF`, `stakeRIF`, `unstakeRIF`, and `castVote`. + +### Why does the ConnectButton show 0 balance while my wallet has funds? + +Do not rely only on third-party account widgets for balance display. The starter kit also reads balances directly with Wagmi `useBalance` for chain-consistent values. + +### Which chain IDs are supported in this implementation? + +Rootstock Mainnet (`30`) and Rootstock Testnet (`31`). The hook and chain utils enforce that range. + +### Where should I add custom contract addresses? + +Use `src/constants/contracts.ts`. Keep all overrides there so QA and deployments stay predictable. + +### What is the fastest way to add proposal creation? + +Reuse the existing `useCollective` hook. Add a proposal form component. Keep simulation before write. Start with `sdk.proposals.createProposal` and `sdk.proposals.createTreasuryTransferProposal`. + +### What is the minimum environment setup? + +Use the **Environment** subsection under **Setup** in the [starter kit README](https://github.com/rsksmart/rootstock-collective-starter-kit#setup). Variable names and required vs optional keys are defined only there so they do not drift from this guide. + +:::tip[Submit a Use Case] + +Fork the starter kit and open a PR with your custom use case. Install `@rsksmart/collective-sdk` and ship your first governance action on Rootstock. + +::: + +## References + +Use these links in the published article and sidebar. + +- [Collective SDK on npm](https://www.npmjs.com/package/@rsksmart/collective-sdk) +- [Collective SDK source](https://github.com/rsksmart/collective-sdk) +- [Rootstock Collective starter kit](https://github.com/rsksmart/rootstock-collective-starter-kit) +- [Rootstock Developers Portal](https://dev.rootstock.io/) +- [Rootstock Collective](https://rootstockcollective.xyz/) diff --git a/docs/06-use-cases/integrate-rif-economy/index.md b/docs/06-use-cases/integrate-rif-economy/index.md new file mode 100644 index 00000000..350930c6 --- /dev/null +++ b/docs/06-use-cases/integrate-rif-economy/index.md @@ -0,0 +1,106 @@ +--- +sidebar_position: 1 +title: RIF economy and governance +sidebar_label: Overview +description: "Multi-sig custody, Collective governance, and RIF utility patterns on Rootstock." +tags: [institutional, governance, dao, safe, multi-sig, fundamentals] +--- + +This section is for teams that need **shared control of funds** and **on-chain governance** on Rootstock. Common building blocks are multi-sig wallets (for example Safe), the Collective SDK for RIF staking and votes, and indexers for operations and reporting. Compliance and policy are still your responsibility, the chain gives you transparent history, not legal sign-off. + + + +## Core pillars + +| Pillar | Description | Primary tool | +| :--- | :--- | :--- | +| **RIF Token** | The RIF (Rootstock Infrastructure Framework) token makes it easier, faster and more rewarding to build on Bitcoin. It also enables governance on RootstockCollective DAO. | [Token](/concepts/rif-suite/token) · [Stake RIF](https://app.rootstockcollective.xyz/) | +| **On-chain voting** | Stake RIF, mint stRIF, and vote on ecosystem proposals. | [Collective SDK](https://github.com/rsksmart/collective-sdk) · [Quick start](/developers/quickstart/collective/) · [Use case guide](/use-cases/integrate-rif-economy/build-dao-voting-collective-sdk/) | +| **Governance apps** | Proposals, treasury moves, and delegation through RootstockCollective. | [RootstockCollective](https://app.rootstockcollective.xyz/) | + +## Key concepts + +### 1. Multi-signature custody (Safe) + +A multi-sig wallet needs a threshold of signatures before a transaction executes. That pattern limits single-key theft and matches how many teams run treasuries. You still define who holds keys and how rotation works. + +### 2. stRIF and delegated voting + +In RootstockCollective, voting power is tied to **stRIF** (staked RIF). Holders vote on proposals or delegate to others. Rules and epochs are defined by the contracts; read them before you promise users a specific voting timeline. + +### 3. On-chain history and your reporting + +Explorers and indexers give you a public history of transfers and events. That helps operations and internal controls. It does not replace accounting, tax, or regulatory workflows your jurisdiction requires. + +## Tools + +* **Safe SDK:** Multi-sig and policy-based custody. +* **Tally:** Governance dashboards for proposals and votes (where supported). +* **Subgraphs / indexers:** Query events for dashboards and internal reporting. + +## Implementation guides + +Published guides in this section are listed below. + +import DocCardList from '@theme/DocCardList'; + + \ No newline at end of file diff --git a/docs/06-use-cases/interoperability/_category_.yml b/docs/06-use-cases/interoperability/_category_.yml new file mode 100644 index 00000000..cb0cfa59 --- /dev/null +++ b/docs/06-use-cases/interoperability/_category_.yml @@ -0,0 +1,5 @@ +label: "Bridge Assets" +position: 5 +link: + type: doc + id: use-cases/interoperability/index \ No newline at end of file diff --git a/docs/06-use-cases/interoperability/_integrate-atlas-bridge-sdk.md b/docs/06-use-cases/interoperability/_integrate-atlas-bridge-sdk.md new file mode 100644 index 00000000..f4816e16 --- /dev/null +++ b/docs/06-use-cases/interoperability/_integrate-atlas-bridge-sdk.md @@ -0,0 +1,74 @@ +--- +sidebar_position: 3 +sidebar_label: Integrate Atlas Bridge SDK +title: Integrate cross-chain flows with the Atlas Bridge SDK +description: "Coordinate Bitcoin and Rootstock assets in your application using the bridge SDK." +tags: [interoperability, bridges, atlas, sdk, rbtc, cross-chain] +--- + +Interoperability is how value and messages move between Bitcoin, Rootstock, and other networks. The **Atlas Bridge SDK** gives your app a single integration surface for cross-chain transfers that involve Bitcoin and Rootstock. This guide describes the moving parts and a **pseudocode** integration shape. Replace types and method names with the versions that ship in your SDK release. + +End users also move assets through [Atlas Bridge](https://atlas.rootstock.io/). Use this guide when you need **in-app** orchestration, status tracking, and custom UX. + +## How the SDK fits together + +The bridge SDK sits above RPC providers for Bitcoin and Rootstock. It tracks lock, confirmation, and release steps so your UI can show accurate state. + +1. **Source chain:** Initiates lock or burn on the chain where the user starts. +2. **Relay and confirmations:** Waits for Bitcoin or Rootstock finality rules before the next step. +3. **Destination chain:** Mints or releases the user’s balance on the target chain. + +## Prerequisites + +* Node.js 18 or newer for a typical web or service integration. +* RPC or node access for Bitcoin and Rootstock (testnet for experiments). +* Test BTC and rBTC for fees on both sides when you run on test networks. +* Install the bridge SDK package and `@rskSmart/w3layer` (or the Web3 layer your team standardizes on). Use the versions from your internal release notes or npm. + +## Initialize the client + +Configure both endpoints before you create a session. The snippet below is illustrative. Match imports and class names to your SDK. + +```typescript +// Network endpoints for Bitcoin and Rootstock +const bridgeConfig = { + bitcoinRpc: "https://your-bitcoin-testnet-endpoint.example", + rootstockRpc: "https://public-node.testnet.rsk.co", +}; + +// Replace BridgeClient with the exported client from your SDK +const bridge = new BridgeClient(bridgeConfig); +``` + +## Start a transfer (example peg-in) + +Moving native BTC toward Rootstock is a peg-in. It is **slow** on purpose. Bitcoin confirmations can take a long time. Show progress in your UI and never promise instant finality. + +```typescript +const transferParams = { + amount: 0.01, + destination: "0xYourRootstockAddress", +}; + +const session = await bridge.initiateTransfer(transferParams); + +session.on("confirming", (count) => { + console.log(`Bitcoin confirmations: ${count}`); +}); +``` + +## Track status + +Poll or subscribe to bridge state so the user sees whether funds are still confirming, ready on Rootstock, or failed. Map SDK states to clear labels in your product. + +```typescript +const status = await bridge.getTransferStatus(session.id); + +if (status === "released") { + console.log("Funds are available on Rootstock."); +} +``` + +## Next steps + +After value is on Rootstock, connect your app to vaults, DEX contracts, or governance flows using the guides under [Generate Yield](/use-cases/btcfi-finance-yield/) and [RIF economy](/use-cases/integrate-rif-economy/). diff --git a/docs/06-use-cases/interoperability/index.md b/docs/06-use-cases/interoperability/index.md new file mode 100644 index 00000000..fca74258 --- /dev/null +++ b/docs/06-use-cases/interoperability/index.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 1 +title: Bridge Assets +sidebar_label: Overview +description: "How Rootstock connects Bitcoin to programmable finance and other chains." +tags: [interoperability, bridges, powpeg, flyover, bitvmx, fundamentals] +--- + +Interoperability is how BTC and rBTC move between Bitcoin, Rootstock, and other chains. Peg-ins, peg-outs, liquidity bridges, and messaging protocols differ by trust model, speed, and cost. Your job is to pick a path that matches your risk budget and to explain that choice to users. + +## Core pillars + +| Pillar | Description | Typical use | +| :--- | :--- | :--- | +| **Atlas** | Product UI for comparing bridge routes between Bitcoin and Rootstock. | [atlas.rootstock.io](https://atlas.rootstock.io/) for operators and users. The Dev Portal Atlas Bridge SDK tutorial is not published yet. | +| **PowPeg** | Two-way peg with federation and HSM-backed signers. | High-value BTC and rBTC moves when you follow protocol rules and confirmations. | +| **Flyover** | Liquidity providers can front funds for faster peg-side flows. | Faster UX when LPs are available on your route. | +| **Union (BitVMX)** | Designs that target lower trust via optimistic checks on Bitcoin. | Advanced integrations, not a generic default. | +| **LayerZero** | Omnichain tokens and messaging to other EVM networks. | Token portability beyond Bitcoin and Rootstock. Published guide: [LayerZero on Rootstock](/use-cases/interoperability/rootstock-layerzero/). | + +## Key concepts + +### 1. Peg-in (Bitcoin to Rootstock) + +You send BTC to a peg-in path on Bitcoin. After enough confirmations, Rootstock credits rBTC to your Rootstock address. Time and fees depend on Bitcoin congestion and policy. + +### 2. Peg-out (Rootstock to Bitcoin) + +You burn or lock rBTC on Rootstock according to the peg-out flow. Native BTC is released on Bitcoin after protocol delays. Peg-outs are **not instant**. + +### 3. Trust and verification + +Some bridges optimize for speed with liquidity or federation assumptions. Others target stronger trust minimization with more moving parts. Pick the path that matches your risk model and disclose it to users. + +## Tools + +* **Flyover SDK:** Fast peg flows where the protocol is supported. +* **Explorers:** Trace peg-in, peg-out, and bridge transactions for support. +* **Atlas:** Route comparison at [atlas.rootstock.io](https://atlas.rootstock.io/). +* **PowPeg app:** User-facing peg walkthroughs under [Resources → PowPeg app](/resources/guides/powpeg-app/overview/). This section targets builders and cross-chain integration patterns. + +## Implementation guides + +Published tutorials in this section are listed below. Draft bridge SDK pages stay out of the sidebar until they are renamed for release. + +import DocCardList from '@theme/DocCardList'; + + diff --git a/docs/02-developers/09-use-cases/defi/rootstock-layerzero.md b/docs/06-use-cases/interoperability/rootstock-layerzero.md similarity index 79% rename from docs/02-developers/09-use-cases/defi/rootstock-layerzero.md rename to docs/06-use-cases/interoperability/rootstock-layerzero.md index 51614786..bc8639a2 100644 --- a/docs/02-developers/09-use-cases/defi/rootstock-layerzero.md +++ b/docs/06-use-cases/interoperability/rootstock-layerzero.md @@ -6,9 +6,9 @@ tags: [rsk, rootstock, layerzero, omnichain, cross chain, oft, defi on bitcoin, description: "This tutorial demonstrates implementing cross-chain token transfers using OFT (Omnichain Fungible Token) between Rootstock Testnet and Ethereum Sepolia Testnet via LayerZero's OFT V2 protocol." --- -Rootstock now integrates with LayerZero, a cross-chain messaging protocol. This integration enables the seamless movement of Bitcoin-backed assets from Rootstock to other blockchains, allowing developers to build [omnichain applications (OApps)](https://docs.layerzero.network/v2/developers/evm/oapp/overview) that interact across multiple chains as if they were one. Users can now move their Bitcoin across different DeFi ecosystems without complicated bridges, high fees, or slow transactions. +Rootstock supports [LayerZero](https://docs.layerzero.network/), a cross-chain messaging protocol. You can build [omnichain applications (OApps)](https://docs.layerzero.network/v2/developers/evm/oapp/overview) that send messages and tokens between Rootstock and other EVM chains. Fees, latency, and trust assumptions still depend on each route and endpoint configuration. -This tutorial demonstrates how to implement cross-chain token transfers using OFT (Omnichain Fungible Token) between Rootstock Testnet and Ethereum Sepolia Testnet via LayerZero's OFT V2 protocol. +This tutorial shows how to implement OFT (Omnichain Fungible Token) transfers between Rootstock Testnet and Ethereum Sepolia using LayerZero OFT V2. ## What you'll learn - Set up Hardhat for cross-chain deployments @@ -29,26 +29,24 @@ To complete this tutorial, you'll need: > Important: Ensure you have sufficient test tokens on both networks. -## Benefits of building cross-chain dApps on Rootstock +## Why teams use LayerZero on Rootstock -- Simplified Cross-Chain Asset Transfers: Eliminate the need for cumbersome and often risky bridging mechanisms. rBTC and RIF can flow freely between Rootstock and other supported chains. -- Enhanced Capital Efficiency: Lower transaction costs and faster confirmation times, driven by LayerZero and Stargate, optimize capital utilization and improve the user experience. -- Expanded DeFi Accessibility: Unlock Bitcoin's liquidity and security for use across a wide range of DeFi protocols on major chains like Ethereum, Base, Arbitrum, and beyond. -- Unified Liquidity: Aggregate liquidity across multiple chains, creating deeper pools and improving trading efficiency. -- Atomic Transactions: Facilitate secure and reliable cross-chain transactions with LayerZero's guaranteed message delivery. -- Programmable Cross-Chain Logic: Construct complex, multi-chain workflows and applications with LayerZero's flexible messaging framework. +- **Asset movement:** You route value through LayerZero’s OFT and related patterns instead of ad hoc bridges. Each path still has its own fees, latency, and trust model. +- **Cost and speed:** Rootstock and the destination chain set gas and confirmation time. Compare endpoints before you commit user flows to a route. +- **Reach:** You can surface Rootstock assets on other EVM chains where your users already hold wallets and liquidity. +- **Liquidity:** Omnichain designs let you reference liquidity on multiple chains. Depth and slippage depend on how you split pools and incentives. +- **Delivery semantics:** LayerZero documents message delivery and executor behavior. Read the path config for your deployment. Do not assume “guaranteed” delivery without checking DVNs and limits. +- **Composable flows:** OApps can chain sends, receives, and off-chain steps. Complexity and failure modes grow with each hop, so design retries and monitoring explicitly. -## Use cases for building cross-chain dApps on Rootstock +## Use cases for cross-chain dApps on Rootstock -The integration with Layerzero opens up a vast array of innovative use cases, extending beyond simple asset transfers. +LayerZero messaging supports more than simple transfers. Typical patterns include: -Developers can now build sophisticated applications that leverage Bitcoin's security and Rootstock's EVM compatibility across multiple chains: - -- Decentralized Exchanges (DEXs) with Cross-Chain Liquidity Pools: Build DEXs that aggregate liquidity from various chains, enabling seamless trading of rBTC and other assets. -- Cross-Chain Lending and Borrowing Protocols: Allow users to lend and borrow rBTC and other assets across different chains, maximizing capital utilization. -- Omnichain Governance Systems: Enable decentralized governance models that span multiple chains, allowing token holders to participate in decision-making regardless of their preferred blockchain. -- Cross-Chain Yield Aggregators: Develop yield optimization platforms that automatically allocate rBTC and other assets to the most profitable opportunities across multiple chains. -- NFT Marketplaces with Cross-Chain Interoperability: Create NFT marketplaces that allow users to buy, sell, and transfer NFTs across different chains, leveraging Bitcoin's security. +- **Cross-chain DEX liquidity:** Pool liquidity across chains. Trading rBTC and other assets still follows each pool’s rules and bridge path. +- **Cross-chain lending and borrowing:** Users supply or borrow on one chain while collateral or settlement lives on another. You must align liquidation, oracles, and bridge timing with your risk model. +- **Omnichain governance:** Votes and execution can span chains when you wire proposals to LayerZero messages. Latency and quorum rules need explicit handling per chain. +- **Cross-chain yield:** Vaults can rebalance across chains. Yield and principal risk depend on each venue’s contracts and the bridge path you use. +- **NFTs across chains:** Marketplaces can list or settle on different chains than mint. Bitcoin finality on Rootstock does not remove smart contract or bridge risk on the other side. ## Getting started @@ -165,7 +163,7 @@ https://repo.sourcify.dev/contracts/full_match/11155111/0xa3725eAC59776F075dC5bb ## Configuring the Omni-chain App (OApp) -LayerZero configures and validates communication between smart contracts across different blockchains. This is done by defining a connection pathway that sets the required send and receive libraries, message verification settings ([DVNs and Executors](https://docs.layerzero.network/v2/developers/evm/developer-overview)), and execution parameters (like gas and value limits). These configurations ensure that the contracts can securely and reliably send and receive messages, allowing for seamless cross-chain interoperability. +LayerZero configures how contracts on different chains talk to each other. You define a pathway with send and receive libraries, verification settings ([DVNs and Executors](https://docs.layerzero.network/v2/developers/evm/developer-overview)), and execution parameters such as gas and value limits. Misconfiguration can strand messages or expose funds, so treat pathway review as part of deployment, not an afterthought. ### Initialize your OApp configurations by running @@ -222,7 +220,7 @@ info: There are 10 transactions required to configure the OApp ... ``` -Once completed, the contracts are now connected, this allows the transfer of tokens from one chain to another. +When wiring finishes, the contracts can move tokens between chains according to the OFT logic and limits you set. ### Functions @@ -302,7 +300,7 @@ Transaction confirmed in block 6406912 Tokens sent successfully! View on [LayerZero Scan](https://testnet.layerzeroscan.com/tx/0xe77899b28a43345fae8006ee5ee86210fedc890076cc934302f36b7db7d99345) ``` -Once the contract is executed, it returns the link to [view on Layerzero scan](https://testnet.layerzeroscan.com/tx/0xe77899b28a43345fae8006ee5ee86210fedc890076cc934302f36b7db7d99345), there you can find the transaction details. Note: Transactions on mainnet might take longer times because of the dedicated resources) +After execution, the CLI prints a link such as [LayerZero Scan](https://layerzeroscan.com/tx/0xe77899b28a43345fae8006ee5ee86210fedc890076cc934302f36b7db7d99345) for that transaction. Mainnet runs can take longer than testnet because of gas markets, executor load, and chain conditions. To monitor your cross-chain transactions: diff --git a/docs/06-use-cases/onboarding-ux/_category_.yml b/docs/06-use-cases/onboarding-ux/_category_.yml new file mode 100644 index 00000000..6f8534bf --- /dev/null +++ b/docs/06-use-cases/onboarding-ux/_category_.yml @@ -0,0 +1,5 @@ +label: "Onboard Users" +position: 3 +link: + type: doc + id: use-cases/onboarding-ux/index \ No newline at end of file diff --git a/docs/06-use-cases/onboarding-ux/index.md b/docs/06-use-cases/onboarding-ux/index.md new file mode 100644 index 00000000..d9d20d78 --- /dev/null +++ b/docs/06-use-cases/onboarding-ux/index.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 1 +title: Onboard Users +sidebar_label: Overview +description: "Tools and patterns that lower friction for Bitcoin dApp onboarding." +tags: [ux, onboarding, rif-relay, rns, account-abstraction, fundamentals] +--- + +Onboarding is where users hit seed phrases, gas, and long addresses. On Rootstock you can use smart wallets, social login, RIF Relay for sponsored gas, and RNS for names. For a concrete Para integration, see [Getting Started with Para](/use-cases/onboarding-ux/para/). For a Wagmi-based kit, see [Reown quick start](/developers/quickstart/reown/). For feature phones without data, see [USSD and Rootstock DeFi](/use-cases/onboarding-ux/ussd-rootstock-defi/) (testnet-oriented architecture). + + + + + +## Core pillars + + + +| Pillar | Description | Primary tool | +| :--- | :--- | :--- | +| **Identity** | Transforming hex addresses into readable, portable Bitcoin identities. | [RIF Name Service (RNS)](https://rns.rifos.org/) | +| **Smart Wallets** | Remove seed phrases and gas hurdles using Para SDK's MPC-based social login and account abstraction on Rootstock. | [Para on Rootstock](/use-cases/onboarding-ux/para/) | +| **USSD access** | Reach users on feature phones via carrier USSD menus and an off-chain relay that talks to Rootstock. | [USSD Rootstock DeFi](/use-cases/onboarding-ux/ussd-rootstock-defi/) | + +## Key concepts + +### 1. Sponsored gas (RIF Relay) + +Most actions still need rBTC for gas unless you sponsor fees. RIF Relay lets a paymaster cover gas or accept fees in an ERC-20 your user already holds. You configure limits and abuse controls in your relayer integration. + +### 2. Social login and account abstraction + +Providers such as Para, Web3Auth, or Privy can create or connect a smart account without forcing a seed phrase on first visit. You still document recovery, device loss, and key material for your product. + +### 3. Human-readable names (RNS) + +RNS maps names to addresses so users send to a short handle instead of a hex string. Integration details are on [RNS](https://rns.rifos.org/). + +## Tools +* **RIF Relay SDK:** The primary library for implementing sponsored and token-paid transactions. +* **Safe SDK:** Build institutional-grade security and account abstraction into your dApp. +* **Web3Auth / Privy / Para:** Integrated social login providers that work out-of-the-box with Rootstock. + +## Implementation guides + +Published guides in this section are listed below. + +import DocCardList from '@theme/DocCardList'; + + \ No newline at end of file diff --git a/docs/02-developers/04-quickstart/para.md b/docs/06-use-cases/onboarding-ux/para.md similarity index 72% rename from docs/02-developers/04-quickstart/para.md rename to docs/06-use-cases/onboarding-ux/para.md index 5e622d8d..8a56621b 100644 --- a/docs/02-developers/04-quickstart/para.md +++ b/docs/06-use-cases/onboarding-ux/para.md @@ -1,32 +1,38 @@ --- -sidebar_position: 320 +sidebar_position: 3 sidebar_label: Para title: Getting Started with Para -description: 'Para is a modern wallet infrastructure for fintech and crypto applications. It provides a comprehensive wallet and authentication suite for crypto developers and apps.' -tags: [rsk, para, developers, developer tools, wallet, rootstock, testing, dApps, smart contracts] +slug: /use-cases/onboarding-ux/para +description: Para is a modern wallet infrastructure for fintech and crypto applications. It provides a comprehensive wallet and authentication suite for crypto developers and apps on Rootstock. +tags: [onboarding, para, wallet, rootstock, account-abstraction, dapps] --- -[Para Wallet](https://www.getpara.com/) is a modern, non-custodial wallet infrastructure for fintech and crypto, offering a comprehensive wallet and authentication suite for web3 apps. It enables secure access and transactions without seed phrases or browser extensions, while keeping users fully in control of their assets. +[Para Wallet](https://www.getpara.com/) is a modern, non-custodial wallet infrastructure for fintech and crypto. It offers a wallet and authentication suite for web3 apps. Users can access and transact without seed phrases or browser extensions while keeping control of their assets. -This walkthrough explores how to use Para in Rootstock using Para SDK. +This walkthrough shows how to use Para on Rootstock with the Para SDK. ## Prerequisites -- Before integrating Para with Rootstock, ensure you have: + +Before integrating Para with Rootstock, ensure you have: + - A Para API key from the [Para Developer Portal](https://developer.getpara.com/) -- Rootstock RPC API Account -- Node.js 18+ and Next.js development environment +- A Rootstock RPC API account +- Node.js 18+ and a Next.js development environment - Basic familiarity with React and TypeScript ## Installation -```node + +```bash npm install @getpara/react-sdk -``` -> **Important Note:** Please make sure to be at least @getpara/react-sdk version 2.2.0 +``` + +**Note:** Use `@getpara/react-sdk` version **2.2.0** or newer. ## Setup Para Provider -Create a ParaSDKProvider that communicates with Rootstock. -```node +Create a `ParaSDKProvider` that communicates with Rootstock. Import `ParaSDKProvider` and related types from `@getpara/react-sdk` per the [Para React SDK docs](https://docs.getpara.com/). + +```tsx import { rootstockTestnet } from "viem/chains"; const ROOTSTOCK_TESTNET = { @@ -130,15 +136,16 @@ export function ParaProvider({ children }: { children: React.ReactNode }) { } ``` -## Key Features -This integration provides a way to use Para Wallet with Rootstock adding custom tokens. -​ -## Complete Example -See the full working example with [Para and Rootstock](https://github.com/rsksmart/examples-hub). +## Key features + +This integration lets you use Para Wallet on Rootstock and surface custom tokens in the modal. + +## Complete example +See the working sample in the [Para and Rootstock examples hub](https://github.com/rsksmart/examples-hub). ## Resources + - [Para Docs](https://docs.getpara.com/v2/introduction/welcome) -- [Rootstock Walkthrough](https://docs.getpara.com/v2/walkthroughs/rootstock) +- [Rootstock walkthrough (Para)](https://docs.getpara.com/v2/walkthroughs/rootstock) - [Para Developer Portal](https://developer.getpara.com/) - diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/_category_.yml b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/_category_.yml similarity index 72% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/_category_.yml rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/_category_.yml index 78601c96..a442cbb8 100644 --- a/docs/02-developers/09-use-cases/ussd-rootstock-defi/_category_.yml +++ b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/_category_.yml @@ -3,5 +3,5 @@ label: USSD Rootstock DeFi position: 4 link: type: generated-index - slug: /developers/use-cases/ussd-rootstock-defi/ + slug: /use-cases/onboarding-ux/ussd-rootstock-defi/ description: "Use USSD to interact with DeFi protocols on Rootstock." \ No newline at end of file diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/architecture.md b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/architecture.md similarity index 100% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/architecture.md rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/architecture.md diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/demo-and-testing.md b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/demo-and-testing.md similarity index 100% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/demo-and-testing.md rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/demo-and-testing.md diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/overview.md b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/overview.md similarity index 76% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/overview.md rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/overview.md index 08261b02..873387e2 100644 --- a/docs/02-developers/09-use-cases/ussd-rootstock-defi/overview.md +++ b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/overview.md @@ -6,7 +6,7 @@ tags: [rsk, rootstock, developers, defi, ussd] description: Learn how to build internet-free decentralized financial services on Rootstock using USSD, enabling P2P transfers and micro-loans on feature phones without internet access. --- -This guide introduces a novel integration architecture that connects **legacy GSM feature phones** to the Rootstock(RSK) blockchain network via USSD (Unstructured Supplementary Service Data). The system enables decentralized financial services, including P2P transfers and micro-loans, for users without smartphone or internet access. +This guide introduces an integration architecture that connects **legacy GSM feature phones** to the Rootstock blockchain network via USSD (Unstructured Supplementary Service Data). The system enables decentralized financial services, including P2P transfers and micro-loans, for users without smartphone or internet access. :::note USSD is a real-time communication protocol built into every GSM network globally. It works on any mobile phone, requires no internet, no app installation, and no data plan, making it one of the most accessible communication channels in the world. @@ -16,7 +16,7 @@ USSD is a real-time communication protocol built into every GSM network globally Web3 services today are largely gated behind smartphones and reliable internet connectivity. Across large parts of Africa, South Asia, and Latin America, hundreds of millions of people still rely on basic feature phones for communication. This creates a clear contradiction because blockchain offers financial inclusion, yet its interfaces exclude the very populations who need it most. -This architecture removes that barrier. By routing USSD sessions through an off-chain relay server that communicates with the Roostock network, anyone with a basic GSM phone and a SIM card can access the following capabilities: +This architecture removes that barrier. By routing USSD sessions through an off-chain relay server that communicates with the Rootstock network, anyone with a basic GSM phone and a SIM card can access the following capabilities: - Check their on-chain token balance. - Send peer-to-peer transfers to other wallet addresses. @@ -41,4 +41,4 @@ A feature phone initiates a USSD session by dialing a shortcode (for example, `* A Node.js Express server receives the USSD payload from a telecom gateway such as Africa's Talking, interprets the user's menu choices, and constructs the appropriate blockchain transaction or read call. 3. **On-Chain Layer** -A Solidity smart contract deployed on the Roostock Testnet manages balances, P2P transfers, and micro-loan logic. The Off-Chain Relay Layer acts as a funded relayer wallet that signs and broadcasts transactions on behalf of the user. \ No newline at end of file +A Solidity smart contract deployed on the Rootstock Testnet manages balances, P2P transfers, and micro-loan logic. The off-chain relay layer acts as a funded relayer wallet that signs and broadcasts transactions on behalf of the user. \ No newline at end of file diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/project-setup.md b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/project-setup.md similarity index 98% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/project-setup.md rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/project-setup.md index b592d717..c84edafc 100644 --- a/docs/02-developers/09-use-cases/ussd-rootstock-defi/project-setup.md +++ b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/project-setup.md @@ -3,7 +3,7 @@ sidebar_label: Project Setup & Smart Contract Deployment sidebar_position: 3 title: Project Setup & Smart Contract Deployment tags: [rsk, rootstock, developers, solidity, hardhat] -description: Scaffold the USSD-Rootstock project using Hardhat 3, write the InclusiveDeFi smart contract, configure the Roostock Testnet network, and deploy using Hardhat Ignition. +description: Scaffold the USSD-Rootstock project using Hardhat 3, write the InclusiveDeFi smart contract, configure the Rootstock Testnet network, and deploy using Hardhat Ignition. --- This page covers everything from scaffolding the project to deploying the `InclusiveDeFi` contract on Rootstock Testnet. By the end of this page, you will have a live contract address on Chain ID 31 that the relay server can interact with. diff --git a/docs/02-developers/09-use-cases/ussd-rootstock-defi/relay-server.md b/docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/relay-server.md similarity index 100% rename from docs/02-developers/09-use-cases/ussd-rootstock-defi/relay-server.md rename to docs/06-use-cases/onboarding-ux/ussd-rootstock-defi/relay-server.md diff --git a/docs/06-use-cases/payments-assets/_agentic-commerce.md b/docs/06-use-cases/payments-assets/_agentic-commerce.md new file mode 100644 index 00000000..a7b5484e --- /dev/null +++ b/docs/06-use-cases/payments-assets/_agentic-commerce.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 3 +sidebar_label: Agentic Commerce with x402 Payment Standard +title: A Developer's Guide to Agentic Commerce using x402 Payment Standard +description: "Utilize the x402 standard to enable autonomous fund deposits and automated settlements for AI agents on Rootstock." +tags: [ai, x402, payments, agents, rbtc, usdc, commerce] +--- + +Agentic commerce refers to software agents that autonomously discover, negotiate, and pay for services. The x402 standard repurposes the dormant "HTTP 402 Payment Required" status code into a functional protocol for machine-to-machine transactions. This tutorial explains how to implement x402 on Rootstock to enable AI agents to pay for resources like API access or data feeds using stablecoins. + +## The x402 Standard Architecture +The x402 protocol operates directly over the HTTP request-response cycle. It eliminates the need for manual API key management or subscription setups. + +* Client (The Agent): It makes a standard HTTP request to a protected resource. + +* Resource Server: It responds with an HTTP 402 status code and a PAYMENT-REQUIRED header containing price, network, and recipient details. + +* Facilitator: This service verifies on-chain signatures and handles the final settlement to the blockchain. + +* Blockchain (Rootstock): It acts as the immutable settlement layer for the transaction. + +## Prerequisites +You must have the following tools configured before implementing agentic payments. + +* Node.js environment with the @coinbase/x402-sdk installed. + +* A Rootstock wallet with USDC or USDRIF for payment. + +* The `@rskSmart/w3layer` for Rootstock network interaction. + +## Implementing the Payment Handshake +The agent must handle the 402 response by signing a payment authorization. You use the SDK to construct this payload without exposing private keys directly to the server. + +### Step 1: Handling the 402 Response +The agent attempts to access a resource and catches the payment requirement. + +```ts +// Initial request to a protected endpoint +const response = await fetch("https://api.rootstock-service.com/data"); + +if (response.status === 402) { + // Extract payment details from the headers + const paymentDetails = response.headers.get("PAYMENT-REQUIRED"); + + // Construct a signed payment authorization + const paymentSignature = await x402.signPayment(paymentDetails, signer); +} +``` + +### Step 2: Retrying with Payment +The agent re-sends the request, including the signature in the `PAYMENT-SIGNATURE` header. + +```ts +// Retry the request with the proof of payment +const paidResponse = await fetch("https://api.rootstock-service.com/data", { + headers: { + "PAYMENT-SIGNATURE": paymentSignature + } +}); + +// Access the granted resource +const data = await paidResponse.json(); +``` + +## Automated Settlements +Settlement occurs when the facilitator verifies the on-chain transfer. On Rootstock, this process leverages the EVM-compatible RVM to finalize the transfer of stablecoins in seconds. + +### Settlement Verification +The server forwards the payload to a facilitator, which validates the signature against the blockchain state. + +* Simulation: The facilitator simulates the transfer to ensure the agent has sufficient funds. + +* Broadcast: The facilitator submits the transaction to the Rootstock network. + +* Confirmation: Once the transaction is mined, the facilitator notifies the resource server to deliver the content. + +## Next Steps +Now that your agent can pay for services, you should build the infrastructure to accept them: \ No newline at end of file diff --git a/docs/06-use-cases/payments-assets/_category_.yml b/docs/06-use-cases/payments-assets/_category_.yml new file mode 100644 index 00000000..73076645 --- /dev/null +++ b/docs/06-use-cases/payments-assets/_category_.yml @@ -0,0 +1,5 @@ +label: "Automate Payments" +position: 7 +link: + type: doc + id: use-cases/payments-assets/index \ No newline at end of file diff --git a/docs/06-use-cases/payments-assets/index.md b/docs/06-use-cases/payments-assets/index.md new file mode 100644 index 00000000..e758bb85 --- /dev/null +++ b/docs/06-use-cases/payments-assets/index.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 1 +title: Automate Payments +sidebar_label: Overview +description: "Tokens, rBTC settlement, and programmable payment patterns on Rootstock." +tags: [payments, assets, erc-20, stablecoins, checkout, fundamentals] +--- + +Programmable payments on Rootstock are normal EVM contracts with Bitcoin-anchored finality. Gas costs and confirmation time depend on network load and how you batch work. **USDRIF**, **RIF Relay**, and HTTP 402 style flows each solve different jobs; pick the stack that matches your product and disclose fees and settlement time to users. + +## Core pillars + +| Pillar | Description | Where to go | +| :--- | :--- | :--- | +| **x402 and agentic commerce** | Machine clients pay for HTTP resources with on-chain settlement. | [Integrating x402 Payments with Rootstock](/resources/tutorials/integrate-x402/) (Resources tutorial) | +| **Testnet mocks (USDT0)** | Practice liquidity and settlement logic on testnet without mainnet risk. | Dev Portal guide not published yet. | +| **ERC-20 and rBTC** | Fungible tokens and native rBTC for checkout, escrow, and streaming. | Contract patterns in your stack (Hardhat, Foundry) plus [RIF Relay](/developers/integrate/rif-relay/overview/) when you need sponsored gas. | + +## Key concepts + +### 1. ERC-20 assets + +ERC-20 tokens work on Rootstock the same way as on other EVM chains. Wallets and indexers you already use apply, but you must verify token addresses per network (mainnet vs testnet). + +### 2. Native rBTC payments + +rBTC is the native gas token and is pegged 1:1 to BTC through the PowPeg. Users need rBTC for gas unless you sponsor fees with RIF Relay or a similar paymaster pattern. + +### 3. Programmable money + +Contracts can hold funds, release them on conditions, or stream them over time. You still need clear failure handling, upgrade policies, and user messaging when a payment path reverts. + +## Tools + +* **Hardhat / Foundry:** Write and test payment and escrow contracts. +* **RIF Relay SDK:** Sponsored or token-paid gas for end users. +* **Explorers and indexers:** Confirm settlement and build support tooling. + +## Implementation guides + +When you publish a guide in this folder (remove the leading `_` from the filename), it appears as a card below. Until then this section stays empty. + +import DocCardList from '@theme/DocCardList'; + + diff --git a/docs/06-use-cases/payments-assets/stablecoin-mock-usdt0.md b/docs/06-use-cases/payments-assets/stablecoin-mock-usdt0.md new file mode 100644 index 00000000..bddc6c47 --- /dev/null +++ b/docs/06-use-cases/payments-assets/stablecoin-mock-usdt0.md @@ -0,0 +1,81 @@ +--- +sidebar_position: 2 +sidebar_label: Mock (USDT0) for Testnet Development +title: Mocking Stablecoins (USDT0) for Testnet Development +description: "Simulate USDT0 and USDRIF liquidity to harden your financial logic and test protocol stability on the Rootstock Testnet." +tags: [btcfi, stablecoins, mocking, testnet, dev-tutorial, rbtc] +--- + +Financial logic requires testing against assets with different decimal precisions and liquidity profiles. Real USDT0 on Rootstock Testnet might be scarce or difficult to acquire in large volumes for stress testing. This tutorial explains how to deploy and use a mock stablecoin contract to simulate high-liquidity environments. + +## The Purpose of Mocking +Testing a protocol with real testnet tokens often limits the scope of your simulations. Mocking allows you to: + +* Control Supply: Mint arbitrary amounts of tokens to test large-scale liquidations. + +* Test Decimals: Ensure your math handles the 6-decimal format used by USDT0 correctly. + +* Simulate Peg Deviations: Manually adjust internal mock state to test how your dApp reacts to a stablecoin losing its peg. + +## Technical Architecture +The mocking workflow sits within the Develop layer of the Rootstock stack. You use an EVM-compatible mock contract to simulate the behavior of a production stablecoin. + +* Mock Contract: An ERC-20 contract with a public mint function and a fixed 6-decimal configuration. + +* Web3 Core Layer: It handles the deployment and subsequent interactions via the RVM. + +* Rootstock Testnet: The sandbox environment where the simulation occurs without using real value. + +## Implementation: The Mock USDT0 Contract +You deploy a simple ERC-20 contract that replicates the interface of USDT0. The key requirement is setting the decimals to 6. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; + +contract MockUSDT0 is ERC20 { + constructor() ERC20("Mock USDT0", "USDT0") {} + + // Override decimals to match production USDT0 + function decimals() public view virtual override returns (uint8) { + return 6; + } + + // Public mint function for testing purposes + // This allows you to create liquidity on demand + function mint(address to, uint256 amount) public { + _mint(to, amount); + } +} +``` + +## Simulating Liquidity for Stress Testing +Once you deploy the contract, you must fund your test accounts to simulate a live market. You use the "Write" function sequence to mint tokens directly to your agent or user addresses. + +### Minting Mock Liquidity +You use the SDK or a script to generate the required funds. + +```ts +// Initialize the contract instance on testnet +const mockUsdt = new ethers.Contract(mockAddress, abi, signer); + +// Mint 1,000,000 Mock USDT0 (remember the 6 decimals) +const amount = ethers.parseUnits("1000000", 6); + +// Execute the mint transaction +const tx = await mockUsdt.mint(testerAddress, amount); +await tx.wait(); + +``` + +## Hardening Financial Logic +Use these mock tokens to test edge cases in your lending or yield protocols. You can simulate events by burning tokens or restricting transfers within the mock contract logic. + +* Liquidation Testing: Mint enough tokens to push a vault's collateral ratio below the threshold. + +* Decimal Precision: Verify that your smart contract does not lose value when converting between 18-decimal rBTC and 6-decimal USDT0. + +## Next Steps +Now that you have simulated liquidity, you should apply it to functional outcomes: \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/02-developers/index.md b/i18n/es/docusaurus-plugin-content-docs/current/02-developers/index.md index 4982345a..26df9700 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/02-developers/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/02-developers/index.md @@ -35,6 +35,6 @@ Esta sección permite a los desarrolladores iniciarse en la blockchain de Rootst | [Guías de integración](/developers/integrate/) | Profundice su conocimiento con guías detalladas y tutoriales informativos que cubren diversos aspectos del desarrollo de Rootstock. | | [JSON-RPC](/developers/rpc-api/) | Pruebe sus dApp en testnet antes de implementarlas en mainnet utilizando los proveedores de la API RPC en Rootstock. | | [Bibliotecas](/developers/libraries/) | Acceda a herramientas y bibliotecas indispensables para agilizar su proceso de desarrollo. | -| [Casos de Uso](/developers/use-cases/) | Explore las guías de casos de uso y tutoriales de la dApp de Rootstock para crear DeFi en Bitcoin, IA y soluciones de cadena cruzada. | +| [Casos de uso](/use-cases/) | Guías y tutoriales de casos de uso para DeFi, incorporación de usuarios, puentes y automatización en Rootstock. | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/02-developers/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/02-developers/index.md index 52075d4b..43c681d2 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/02-developers/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/02-developers/index.md @@ -35,6 +35,6 @@ Rootstockの開発者向け概要セクションへようこそ。 | [統合ガイド](/developers/integrate/) | Rootstock開発のさまざまな側面を説明する詳細なガイドと有益なチュートリアルで、知識を深めます。 | | [JSON-RPC](/developers/rpc-api/) | メインネットにデプロイする前に、RootstockのRPC APIプロバイダーを活用して、数分以内にテストネットでdAppsをテストします。 | | [ライブラリ](/developers/libraries/) | 開発プロセスの効率化に必須のツールとライブラリにアクセスします。 | -| [使用例](/developers/use-cases/) | ビットコイン、AI、クロスチェーンソリューションでDeFiを構築するためのRootstock dAppユースケースガイドとチュートリアルをご覧ください。 | +| [ユースケース](/use-cases/) | Rootstock上のDeFi、オンボーディング、ブリッジ、自動化に関するユースケースガイドとチュートリアル。 | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/05-dev-tools/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/05-dev-tools/index.md index 5a2655d4..ab987c97 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/05-dev-tools/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/05-dev-tools/index.md @@ -637,7 +637,7 @@ description: スマートコントラクト開発ツールと言語のキュレ title="LayerZero" subtitle="クロスチェーンブリッジ" color="orange" - linkHref="/developers/use-cases/defi/rootstock-layerzero/" + linkHref="/use-cases/interoperability/rootstock-layerzero/" linkTitle="クロスチェーンdAppを構築" description="LayerZeroは、Rootstockから他のブロックチェーンへのBitcoinバック資産のシームレスな移動を可能にするクロスチェーンメッセージングプロトコルで、複数のチェーンを一体のように扱えるオムニチェーンアプリケーション（OApps）を構築可能。" /> diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/02-developers/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/02-developers/index.md index bd4c0716..68e6ef56 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/02-developers/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/02-developers/index.md @@ -35,6 +35,6 @@ Rootstock 개발자 개요 섹션에 오신 것을 환영합니다. | [연동 가이드](/developers/integrate/) | Rootstock 개발의 다양한 측면을 다루는 자세한 가이드와 유익한 튜토리얼을 통해 지식을 더욱 깊이 있게 쌓아보세요. | | [JSON-RPC](/developers/rpc-api/) | Rootstock의 RPC API 공급자를 활용하면, 메인넷에 배포하기 전에 몇 분 만에 테스트넷에서 dApp을 테스트할 수 있습니다. | | [라이브러리](/developers/libraries/) | 개발 과정을 간소화해 줄 핵심 도구와 라이브러리를 활용하세요. | -| [사용 사례](/developers/use-cases/) | 비트코인, AI, 크로스체인 솔루션에서 탈중앙 금융을 구축하기 위한 루트스탁 dApp 사용 사례 가이드와 튜토리얼을 살펴보세요. | +| [사용 사례](/use-cases/) | 비트코인, AI, 크로스체인 솔루션에서 탈중앙 금융을 구축하기 위한 루트스탁 dApp 사용 사례 가이드와 튜토리얼을 살펴보세요. | diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/05-dev-tools/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/05-dev-tools/index.md index b28e6774..fdde370b 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/05-dev-tools/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/05-dev-tools/index.md @@ -638,7 +638,7 @@ description: Rootstock에서 스마트 컨트랙트를 개발하고 배포하는 title="Layerzero" subtitle="크로스체인 브릿지" color="orange" - linkHref="/developers/use-cases/defi/rootstock-layerzero/" + linkHref="/use-cases/interoperability/rootstock-layerzero/" linkTitle="크로스체인 dApps 개발" description="LayerZero는 크로스체인 메시징 프로토콜로, Rootstock에서 다른 블록체인으로 비트코인 기반 자산을 원활하게 이동할 수 있도록 해줍니다. 이를 통해 개발자는 여러 체인을 마치 하나처럼 연결해 상호작용하는 옴니체인 애플리케이션(OApp)을 구축할 수 있습니다." /> diff --git a/src/components/Homepage/HomepageSectionUseCases/index.js b/src/components/Homepage/HomepageSectionUseCases/index.js new file mode 100644 index 00000000..a15dc5d5 --- /dev/null +++ b/src/components/Homepage/HomepageSectionUseCases/index.js @@ -0,0 +1,114 @@ +import Card from "/src/components/Card"; +import Translate from "@docusaurus/core/lib/client/exports/Translate"; + +const useCaseData = { + title: Browse by use case, + description: null, + cards: [ + { + title: Generate yield, + color: 'orange', + description: ( + BTCFi context and vault-related work on Rootstock. Vault SDK tutorials are not on the portal yet. Live vault access depends on each program. + ), + list: [ + { + title: Generate Yield, + href: '/use-cases/btcfi-finance-yield/', + }, + ], + }, + { + title: Bridge assets, + color: 'cyan', + description: ( + Move value between Bitcoin, Rootstock, and other chains. End-user peg guides sit under Resources. Published Dev Portal guide: LayerZero OFT. + ), + list: [ + { + title: Bridge Assets, + href: '/use-cases/interoperability/', + }, + { + title: LayerZero OFTs on Rootstock, + href: '/use-cases/interoperability/rootstock-layerzero/', + }, + ], + }, + { + title: Onboard users, + color: 'green', + description: ( + Lower onboarding friction with smart wallets, familiar login, or USSD where data networks are not available. + ), + list: [ + { + title: Getting started with Para, + href: '/use-cases/onboarding-ux/para/', + }, + { + title: Internet-free DeFi with USSD, + href: '/use-cases/onboarding-ux/ussd-rootstock-defi/', + }, + ], + }, + { + title: Automation and AI, + color: 'pink', + description: ( + Connect MCP, SDK modules, and guarded permissions so automation can read the chain and submit limited transactions. + ), + list: [ + { + title: Conversational app with on-chain actions, + href: '/use-cases/ai-automation/ai-agent-rootstock/', + }, + // { + // title: Integrate SDK logic into workflows, + // href: '/use-cases/ai-automation/integrate-rootstock-sdk/', + // }, + ], + }, + { + title: RIF economy and payments, + color: 'orange', + description: ( + Collective governance and machine-payable HTTP flows. x402 is covered in the Resources tutorial linked below. + ), + list: [ + { + title: DAO voting with Collective SDK, + href: '/use-cases/integrate-rif-economy/build-dao-voting-colollective-sdk/', + }, + { + title: x402 payments tutorial, + href: '/resources/tutorials/integrate-x402/', + }, + ], + }, + ] +}; + +export default function HomepageSectionUseCases() { + return ( +
+
+ {useCaseData.title && ( +

{useCaseData.title}

+ )} + {useCaseData.description && ( +
+ {useCaseData.description} +
+ )} +
+
+ {useCaseData.cards.map((item, idx) => ( +
+ +
+ ))} +
+
+ ); +} diff --git a/src/css/custom.css b/src/css/custom.css index cde99f90..9a2040ff 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -11,4 +11,4 @@ /* For readability concerns, you should choose a lighter palette in dark mode. */ [data-theme='dark']:root { -} +} \ No newline at end of file diff --git a/src/pages/index.js b/src/pages/index.js index ac1f2d32..3b1323db 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -6,6 +6,7 @@ import HomepageSectionGuides from "/src/components/Homepage/HomepageSectionGuide import HomepageSectionWelcome from "/src/components/Homepage/HomepageSectionWelcome"; import HomepageSectionDevTools from "/src/components/Homepage/HomepageSectionDevTools"; import HomepageSectionProducts from "/src/components/Homepage/HomepageSectionProducts"; +import HomepageSectionUseCases from "/src/components/Homepage/HomepageSectionUseCases"; import HomepageSectionCommunity from "/src/components/Homepage/HomepageSectionCommunity"; import HomepageAside from "/src/components/Homepage/Aside"; import React from "react"; @@ -22,6 +23,7 @@ export default function Home() { + diff --git a/src/scss/pages/_front.scss b/src/scss/pages/_front.scss index adfaed60..59935016 100644 --- a/src/scss/pages/_front.scss +++ b/src/scss/pages/_front.scss @@ -116,3 +116,196 @@ height: 450px; } } + +/* Unified Architecture Styles */ + +.rootstock-stack-container { + + background-color: #000000; + + padding: 2.5rem; + + border-radius: 8px; + + font-family: 'Inter', sans-serif; /* Fallback for Rootstock Sans Body */ + + color: #FAF9F5; /* Brand White */ + + margin: 2rem 0; + + box-sizing: border-box; + +} + + + +.rootstock-stack-container * { + + box-sizing: border-box; + +} + + + +.stack-layer { + + display: flex; + + margin-bottom: 12px; + + min-height: 60px; + + width: 100%; + +} + + + +.layer-label { + + writing-mode: vertical-rl; + + transform: rotate(180deg); + + padding: 10px; + + font-size: 0.75rem; + + text-transform: uppercase; + + display: flex; + + align-items: center; + + justify-content: center; + + font-weight: 800; /* Rootstock Sans Bold */ + + color: #000000; + + width: 45px; /* Fixed anchor width for all labels */ + + flex-shrink: 0; + + border-radius: 4px 0 0 4px; + +} + + + +.layer-content { + + flex-grow: 1; + + display: grid; + + grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); + + color: #000000; + + border-radius: 0 4px 4px 0; + +} + + + +.sub-module { + + display: flex; + + align-items: center; + + justify-content: center; + + padding: 15px; + + text-align: center; + + font-size: 0.95rem; + + font-weight: 700; + + letter-spacing: 0.5px; + +} + + + +/* Unified Tooling Fix: Matches Width of .layer-content exactly */ + +.layer-tooling-container { + + display: flex; + + width: 100%; + + margin-bottom: 12px; + +} + + + +.tooling-anchor { + + width: 45px; /* Matches .layer-label */ + + flex-shrink: 0; + +} + + + +.layer-tooling { + + flex-grow: 1; + + border: 1.5px dashed #9E76FF; + + // background-color: transparent; + + color: #000000; + + display: flex; + + align-items: center; + + justify-content: center; + + font-size: 0.95rem; /* Adjusted for longer text */ + + font-weight: 600; + + letter-spacing: 2px; + + min-height: 50px; + + border-radius: 4px; /* Consistent rounding */ + + margin-left: 0; /* Ensures it starts exactly where the colors start */ + +} + + + +/* Optional: Add a small gap if the colored boxes have a slight separation from the labels */ + + .layer-content, .layer-tooling { + + margin-left: 2px; + +} + + + +/* Brand Palette */ + +.bg-pink { background-color: #FF71E1; } + +.bg-cyan { background-color: #08FFD0; } + +.bg-green { background-color: #79C600; } + +.bg-orange { background-color: #FF9100; } + +.bg-purple { background-color: #9E76FF; } + diff --git a/src/theme/DocCardList/index.js b/src/theme/DocCardList/index.js index ac7369e2..323c222e 100644 --- a/src/theme/DocCardList/index.js +++ b/src/theme/DocCardList/index.js @@ -1,19 +1,56 @@ import React from 'react'; import clsx from 'clsx'; +import {useLocation} from '@docusaurus/router'; import { useCurrentSidebarCategory, filterDocCardListItems, } from '@docusaurus/theme-common'; import DocCard from '@theme/DocCard'; + +/** + * useCurrentSidebarCategory() throws when the current page is not a category + * index (e.g. a section has only index.md and every other doc is _-prefixed and + * excluded). Swallow that case so overview pages still render. + */ +class DocCardListCategoryBoundary extends React.Component { + constructor(props) { + super(props); + this.state = {hideList: false}; + } + + static getDerivedStateFromError(error) { + const message = String(error?.message || ''); + if (message.includes('not associated with a category')) { + return {hideList: true}; + } + return null; + } + + render() { + if (this.state.hideList) { + return null; + } + return this.props.children; + } +} + function DocCardListForCurrentSidebarCategory({className}) { const category = useCurrentSidebarCategory(); return ; } + export default function DocCardList(props) { const {items, className} = props; + const location = useLocation(); + if (!items) { - return ; + return ( + + + + ); } + const filteredItems = filterDocCardListItems(items); return (
diff --git a/vercel.json b/vercel.json index 11955c96..529e35f8 100644 --- a/vercel.json +++ b/vercel.json @@ -653,28 +653,26 @@ {"source": "/resources/guides/eas/", "destination": "/dev-tools/attestations/eas/"}, {"source": "/resources/guides/eas/overview/", "destination": "/dev-tools/attestations/eas/overview/"}, {"source": "/resources/guides/eas/user-guide/", "destination": "/dev-tools/attestations/eas/user-guide/"}, - {"source": "/resources/guides/runes-rootstock/", "destination": "/developers/use-cases/runes-rootstock/"}, - {"source": "/resources/guides/runes-rootstock/overview/", "destination": "/developers/use-cases/runes-rootstock/overview/"}, - {"source": "/resources/guides/runes-rootstock/runes-setup/", "destination": "/developers/use-cases/runes-rootstock/runes-setup/"}, - {"source": "/resources/guides/runes-rootstock/mock-contract-walthrough/", "destination": "/developers/use-cases/runes-rootstock/mock-contract-walthrough/"}, - {"source": "/resources/guides/runes-rootstock/deploy-mockbridge-contract/", "destination": "/developers/use-cases/runes-rootstock/deploy-mockbridge-contract/"}, - {"source": "/resources/guides/runes-rootstock/airdrop-giveaway-machine/", "destination": "/developers/use-cases/runes-rootstock/airdrop-giveaway-machine/"}, - {"source": "/resources/guides/runes-rootstock/governance-dashboard/", "destination": "/developers/use-cases/runes-rootstock/governance-dashboard/"}, + {"source": "/developers/quickstart/para", "destination": "/use-cases/onboarding-ux/para/"}, + {"source": "/developers/quickstart/para/", "destination": "/use-cases/onboarding-ux/para/"}, + {"source": "/use-cases/onboarding-ux/smart-wallet-para-sdk/", "destination": "/use-cases/onboarding-ux/para/"}, {"source": "/developers/use-cases/rootstock-layerzero/", "destination": "/developers/use-cases/defi/rootstock-layerzero/"}, {"source": "/developers/use-cases/ai-agent-rootstock/", "destination": "/developers/use-cases/ai/ai-agent-rootstock/"}, - {"source": "/dev-tools/node-rpc/blast-api/", "destination": " /dev-tools/node-rpc/"}, - {"source": "/dev-tools/no-code/cryptodo/", "destination": "/dev-tools/no-code/"}, - {"source": "/dev-tools/oracles/umbrellanetwork/", "destination": "/dev-tools/oracles/"} - ], - "headers": [ - { - "source": "/(.*)\\.md", - "headers": [ - {"key": "Content-Type", "value": "text/plain; charset=utf-8"}, - {"key": "X-Content-Type-Options", "value": "nosniff"}, - {"key": "X-Robots-Tag", "value": "googlebot: noindex, nofollow, bingbot: noindex, nofollow"}, - {"key": "Cache-Control", "value": "public, max-age=3600, must-revalidate"} - ] - } + {"source": "/developers/use-cases/ai/ai-agent-rootstock/", "destination": "/use-cases/ai-automation/ai-agent-rootstock/"}, + {"source": "/developers/use-cases/ai/mcp-rootstock/", "destination": "/use-cases/ai-automation/mcp-rootstock/"}, + {"source": "/developers/use-cases/defi/rootstock-layerzero/", "destination": "/use-cases/interoperability/rootstock-layerzero/"}, + {"source": "/developers/use-cases/ussd-rootstock-defi/:path*", "destination": "/use-cases/onboarding-ux/ussd-rootstock-defi/:path*"}, + {"source": "/developers/use-cases/", "destination": "/use-cases/"}, + {"source": "/use-cases/ai-emerging/ai-agent-rootstock/", "destination": "/use-cases/ai-automation/ai-agent-rootstock/"}, + {"source": "/use-cases/ai-emerging/mcp-rootstock/", "destination": "/use-cases/ai-automation/mcp-rootstock/"}, + {"source": "/use-cases/ai-agents/:path*", "destination": "/use-cases/ai-automation/:path*"}, + {"source": "/use-cases/btcfi-finance/:path*", "destination": "/use-cases/btcfi-finance-yield/:path*"}, + {"source": "/use-cases/interoperability/integrate-super-bridge-sdk/", "destination": "/use-cases/interoperability/"}, + {"source": "/use-cases/interoperability/integrate-atlas-bridge-sdk/", "destination": "/use-cases/interoperability/"}, + {"source": "/use-cases/btcfi-finance-yield/yield-vaults", "destination": "/use-cases/btcfi-finance-yield/yield-vaults-sdk/"}, + {"source": "/use-cases/btcfi-finance-yield/yield-vaults/", "destination": "/use-cases/btcfi-finance-yield/yield-vaults-sdk/"}, + {"source": "/use-cases/btcfi-finance-yield/automate-yield-vault/", "destination": "/use-cases/btcfi-finance-yield/"}, + {"source": "/use-cases/payments-assets/agentic-commerce/", "destination": "/use-cases/payments-assets/"} + ] } \ No newline at end of file