Add comprehensive documentation for recursive delegation and update relevant links throughout the project

Sipher · Sipher · commit 0a2816003ce5 · 2025-08-06T16:44:52.000-03:00
diff --git a/DOCUMENTATION_TODOS.md b/DOCUMENTATION_TODOS.md
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -62,6 +62,7 @@ export default defineConfig({
               items: [
                 { label: "Agent Registration", slug: "explanations/builders/agent-registration" },
                 { label: "Agent Editing", slug: "explanations/builders/agent-editing" },
+                { label: "Recursive Delegation", slug: "explanations/builders/recursive-delegation" },
                 { label: "Demand Signaling", slug: "explanations/builders/demand-signaling" },
                 { label: "Agent Server", slug: "explanations/builders/agent-server" },
                 { label: "Agent Client", slug: "explanations/builders/agent-client" },
diff --git a/public/images/how-to-guide/bridge-to-base/connected-to-torus-evm.png b/public/images/how-to-guide/bridge-to-base/connected-to-torus-evm.png
diff --git a/src/content/docs/explanations/builders/agent-editing.mdx b/src/content/docs/explanations/builders/agent-editing.mdx
@@ -35,7 +35,7 @@ This balances blockchain immutability with the flexibility needed for comprehens
 
 - **[Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/)** - Initial agent creation and ownership establishment
 - **[Demand Signaling](https://docs.torus.network/explanations/builders/demand-signaling/)** - How agents coordinate through signals
-- **[Root Agents](https://docs.torus.network/explanations/goal-leaders/goal-leaders/)** - Special considerations for DAO-approved agents
+- **[Root Agents](https://docs.torus.network/explanations/goal-leaders/root-agents/)** - Special considerations for DAO-approved agents
 
 <Aside type="tip" title="Ready to Update Your Agent?">
   Follow our [step-by-step guide to edit your agent](https://docs.torus.network/how-to-guides/builders/edit-your-agent/) for practical instructions.
diff --git a/src/content/docs/explanations/builders/demand-signaling.mdx b/src/content/docs/explanations/builders/demand-signaling.mdx
@@ -33,9 +33,9 @@ If you are using a different schema, fully specify it.
 ### Related Concepts
 
 - **[Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/)** - How agents become discoverable
-- **[Root Agents](https://docs.torus.network/explanations/goal-leaders/goal-leaders/)** - Agents with direct emission access
+- **[Root Agents](https://docs.torus.network/explanations/goal-leaders/root-agents/)** - Agents with direct emission access
 - **[Agent Server Setup](https://docs.torus.network/explanations/builders/agent-server/)** - Recommended endpoint interface examples
-- **[Tokenomics](https://docs.torus.network/getting-started/tokenomics/)** - Understanding emission mechanisms
+- **[Tokenomics](https://docs.torus.network/explanations/holders/tokenomics/)** - Understanding emission mechanisms
 
 <Aside type="tip" title="Ready to Create a Signal?">
   Follow our [step-by-step guide to create a signal](https://docs.torus.network/how-to-guides/builders/create-signal/) to start signaling demand for capabilities.
diff --git a/src/content/docs/explanations/builders/recursive-delegation.mdx b/src/content/docs/explanations/builders/recursive-delegation.mdx
@@ -0,0 +1,51 @@
+---
+title: Recursive Delegation
+description: Understanding recursive permission delegation and how it enables specialized permission routing and granular responsibility distribution.
+---
+
+import {
+  Aside,
+  Card,
+  CardGrid,
+} from "@astrojs/starlight/components";
+
+Recursive delegation *(Re-Delegation)** allows agents to re-delegate all types of permissions they receive, creating delegation trees of specialized responsibilities.   
+This allows fluid discovery of the best-fit agent for any permission and allows granular partitioning of broad responsibilities.   
+Each re-delegation creates a new permission, with depth measured as delegation-step distance from the root capability owner for each capability individually.
+
+### Crucial Functions
+
+**Specialized Routing**: Agents can focus purely on routing delegations to the best-qualified agents at any moment,
+with routers recursively delegating to better routers.
+
+**Granular Partitioning**: Wide responsibility scopes can be flexibly divided across self-configuring agent trees,
+with each delegation step narrowing the scope.
+
+### Permission Contents Delegation
+
+Recursive delegation operates on permission contents (controls) rather than permissions themselves, enabling sub-scoping and granular partitioning.
+
+For capability permissions, agents delegate specific namespace paths rather than entire permission sets. Each receiving agent can create new capability permissions from any position within the delegated namespace, allowing recursive tree partitioning.
+
+### Key Rules
+
+- **Revocation**: When a parent revokes, all sub-delegations revoke in the same block.   
+Child revocation terms cannot be less restrictive than parent terms.
+- **Depth**: Measured per capability from root owner to current holder, with maximum of 8 levels.
+- *Coming Soon Rules*
+  - ***Constraints**: Each delegation step can add constraints that accumulate as "gates".   
+  All gates must pass for control to be exercised*.
+  - ***Inheritance**: Permission contents inherit all constraints through delegation chains, with new constraints layering on top.*
+
+
+
+### Related Concepts
+
+- **[Permission System](https://docs.torus.network/explanations/v05/permissions/)** - Core permission mechanics and delegation basics
+- **[Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/)** - How agents become capable of receiving delegations  
+- **[Root Agents](https://docs.torus.network/explanations/goal-leaders/root-agents/)** - Agents with direct emission access for delegation
+
+<Aside type="tip" title="Ready to Implement Recursive Delegation?">
+  Stay tuned for our upcoming [step-by-step guide to recursive delegation](https://docs.torus.network/how-to-guides/builders/recursive-delegation/)
+ for practical implementation instructions.
+</Aside>
diff --git a/src/content/docs/explanations/goal-leaders/emission-proposals.mdx b/src/content/docs/explanations/goal-leaders/emission-proposals.mdx
@@ -50,7 +50,7 @@ For a proposal to pass, it must meet two requirements:
 ## Related Concepts
 
 - **[Governance & DAO](https://docs.torus.network/explanations/v05/governance-dao/)** - Understanding the broader DAO framework
-- **[Tokenomics](https://docs.torus.network/getting-started/tokenomics/)** - How TORUS token economics work
+- **[Tokenomics](https://docs.torus.network/explanations/holders/tokenomics/)** - How TORUS token economics work
 - **[Permission System](https://docs.torus.network/explanations/v05/permissions/)** - How governance permissions enable proposal creation
 
 <Aside type="tip" title="Ready to Create a Proposal?">
diff --git a/src/content/docs/explanations/goal-leaders/root-agents.mdx b/src/content/docs/explanations/goal-leaders/root-agents.mdx
@@ -32,7 +32,7 @@ Successful applicants demonstrate credible execution, active community participa
 
 - **[Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/)** - Technical details of agent registration
 - **[Governance & DAO](https://docs.torus.network/explanations/v05/governance-dao/)** - Understanding DAO decision-making processes  
-- **[Tokenomics](https://docs.torus.network/getting-started/tokenomics/)** - How Root Agents access and use network emissions
+- **[Tokenomics](https://docs.torus.network/explanations/holders/tokenomics/)** - How Root Agents access and use network emissions
 
 <Aside type="tip" title="Ready to Apply?">
   Follow our [step-by-step application guide](https://docs.torus.network/how-to-guides/goal-leaders/become-a-root-agent/) to submit your Root Agent application.
diff --git a/src/content/docs/explanations/holders/staking.mdx b/src/content/docs/explanations/holders/staking.mdx
@@ -30,7 +30,7 @@ and earn rewards while supporting the agents and initiatives they believe in.
 
 ## Related Concepts
 
-- **[Tokenomics](https://docs.torus.network/getting-started/tokenomics/)** - Understanding TORUS token economics and emission structure
+- **[Tokenomics](https://docs.torus.network/explanations/holders/tokenomics/)** - Understanding TORUS token economics and emission structure
 - **[Emission Proposals](https://docs.torus.network/explanations/goal-leaders/emission-proposals/)** - How staking parameters can be adjusted through governance
 - **[Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/)** - Understanding the agents you can support through staking
 
diff --git a/src/content/docs/explanations/table-of-contents.mdx b/src/content/docs/explanations/table-of-contents.mdx
@@ -13,7 +13,7 @@ import {
 
 Welcome to the **Explanations** section of the Torus documentation.
 
-If you need to accomplish a specific task, check out our [How-to Guides](https://docs.torus.network/how-to-guides/start-here/) instead.   
+If you need to accomplish a specific task, check out our [How-to Guides](https://docs.torus.network/how-to-guides/table-of-contents/) instead.   
 
 These explanations provide deep understanding of how Torus works, the concepts, mechanisms of Torus.   
 
@@ -46,6 +46,7 @@ Understanding how agent systems work within Torus:
 
 - [Agent Registration](https://docs.torus.network/explanations/builders/agent-registration/) — Registration economics, burn mechanisms, and discovery
 - [Agent Editing](https://docs.torus.network/explanations/builders/agent-editing/) — Update mechanics and storage architecture
+- [Recursive Delegation](https://docs.torus.network/explanations/builders/recursive-delegation/) — Re-delegation of permissions and specialized responsibility trees
 - [Demand Signaling](https://docs.torus.network/explanations/builders/demand-signaling/) — Capability coordination and economic incentives
 - [Agent Server](https://docs.torus.network/explanations/builders/agent-server/) — API architecture, authentication, and capability sharing
 - [Agent Client](https://docs.torus.network/explanations/builders/agent-client/) — Communication patterns and authentication flow
diff --git a/src/content/docs/how-to-guides/holders/bridge-from-base.mdx b/src/content/docs/how-to-guides/holders/bridge-from-base.mdx
@@ -19,6 +19,7 @@ import metamaskConnectEvm from '/public/images/how-to-guide/bridge-to-base/metam
 import fillInFormToConvertTorusEvmNativeTorus from '/public/images/how-to-guide/bridge-to-base/fill-in-form-to-convert-torus-evm-native-torus.png';
 import confirmTransactionInMetamaskTorusEvmToTorus from '/public/images/how-to-guide/bridge-to-base/confirm-transaction-in-metamask-torus-evm-to-torus.png';
 import torusEvmConvertSuccessfully from '/public/images/how-to-guide/bridge-to-base/torus-evm-convert-successfully.png';
+import connectedToTorusEvm from '/public/images/how-to-guide/bridge-to-base/connected-to-torus-evm.png';
 
 In this guide, we'll **bridge TORUS between Torus and Base**.  
 This process is necessary in order to obtain **Native TORUS**, which is required to interact with Torus directly.
@@ -59,7 +60,9 @@ To keep things clear and concise, **Native TORUS** will be referred to as **TORU
 
 <Aside type="danger">
   Avoid storing BASE TORUS in SubWallet, as it will cause issues with the bridge that could result in loss of funds.
-</Aside> 
+</Aside>
+
+ 
 
 ## Steps for the Bridge Process
 
@@ -108,15 +111,36 @@ To keep things clear and concise, **Native TORUS** will be referred to as **TORU
    <ClickableImage src={metamaskConnectEvm} alt="SubWallet and MetaMask connect screen" />
 
 
-1. **Swap from Torus EVM to Torus**
+2. **Verify you're connected to Torus EVM**  
+   Make sure MetaMask is connected to the Torus EVM network. You should see "Torus EVM" in your MetaMask network dropdown.
+   
+   <ClickableImage src={connectedToTorusEvm} alt="MetaMask connected to Torus EVM" />
+   
+   <Aside type="note" title="Do not see Torus EVM?">
+   **If MetaMask shows a different network or the Bridge doesn't automatically switch to Torus EVM**, you may need to manually add the network to your MetaMask wallet first.
+
+   **Torus EVM Network Configuration:**
+   - **Network Name**: Torus EVM
+   - **Default RPC URL**: https://api.torus.network   
+     *(Alternate: https://api-hyperlane.nodes.torus.network)*
+   - **Chain ID**: 21000
+   - **Currency Symbol**: TORUS
+   - **Block Explorer**: https://blockscout.torus.network
+
+   **MetaMask Setup:** Follow [MetaMask's guide to add custom networks](https://support.metamask.io/networks-and-sidechains/managing-networks/how-to-add-a-custom-network-rpc/) using the configuration above, then return to the Bridge and retry your transaction.
+
+   The Bridge will attempt to add this network automatically, but manual setup ensures a smooth experience if the auto-switch fails.
+   </Aside>
+
+3. **Swap from Torus EVM to Torus**
    - Make sure you are **connected** in **Both Wallets**
    - Make sure you are in the <RedText variant="light">**correct Tab**</RedText>, <RedText variant="light">**TORUS EVM - Base**</RedText>
    - Make sure it is <RedText variant="light">FROM</RedText>**Torus EVM** <RedText variant="light">TO</RedText> **Torus**
 
    Fill in the form with the amount you want to convert, after confirmation, you will be prompted to sign the transaction in Torus.
    <ClickableImage src={fillInFormToConvertTorusEvmNativeTorus} alt="Convert Torus EVM to Native TORUS" />
 
-2. **Confirm the transaction**  
+4. **Confirm the transaction**  
    After filling in the form, you will be prompted to confirm the transaction in Metamask.
    <Aside type="caution">
       Always verify the transaction in MetaMask before signing it, as it is your responsibility to verify the transaction details.  
@@ -125,7 +149,7 @@ To keep things clear and concise, **Native TORUS** will be referred to as **TORU
    
    <ClickableImage src={confirmTransactionInMetamaskTorusEvmToTorus} alt="Confirm the transaction in MetaMask" />
 
-3. **Confirmation of the swap**  
+5. **Confirmation of the swap**  
    After the transaction succeeds, your Torus EVM should now be displayed as TORUS as it was successfully swapped.
    This process can take a while to complete on the blockchain,
    so <RedText variant="light">please wait a few minutes and refresh the page.</RedText>   
@@ -144,7 +168,7 @@ Now that you have TORUS tokens, you can:
 - **Start earning rewards**: [Stake your TORUS](https://docs.torus.network/how-to-guides/holders/stake-your-torus/) to support agents and earn emissions
 - **Become an agent**: [Register an agent](https://docs.torus.network/how-to-guides/builders/register-an-agent/) to provide services and earn directly
 - **Explore the ecosystem**: Browse agents and allocators on the [Torus Portal](https://portal.torus.network/)
-- **Understand tokenomics**: Learn about [TORUS economics](https://docs.torus.network/getting-started/tokenomics/) and emission mechanisms
+- **Understand tokenomics**: Learn about [TORUS economics](https://docs.torus.network/explanations/holders/tokenomics/) and emission mechanisms
 
  Connect with the community:
 - [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements
diff --git a/src/content/docs/how-to-guides/holders/stake-your-torus.mdx b/src/content/docs/how-to-guides/holders/stake-your-torus.mdx
@@ -161,7 +161,7 @@ Staking your TORUS allows you to earn emission rewards while supporting agents y
 Now that you're earning emissions, you might want to:
 
 - **Optimize your strategy**: Monitor agent performance on the [Allocator tab](https://portal.torus.network/root-allocator) and adjust allocations
-- **Understand the system**: Learn about [tokenomics](https://docs.torus.network/getting-started/tokenomics/) and how emissions flow through the network
+- **Understand the system**: Learn about [tokenomics](https://docs.torus.network/explanations/holders/tokenomics/) and how emissions flow through the network
 - **Receive Updates**: Follow [Torus on Twitter](https://x.com/torus_network) to stay informed about the latest developments —
 this can help you evaluate which agents are most promising for allocation and potential rewards.
 
