diff --git a/astro.config.mjs b/astro.config.mjs index 27470ff..e45b785 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -89,8 +89,8 @@ export default defineConfig({ { label: "Register an Agent", slug: "how-to-guides/builders/register-an-agent" }, { label: "Edit your Agent", slug: "how-to-guides/builders/edit-your-agent" }, { label: "Manage Capabilities", slug: "how-to-guides/builders/manage-capabilities" }, + { label: "Manage Permissions", slug: "how-to-guides/builders/manage-permissions" }, { label: "Create a Signal", slug: "how-to-guides/builders/create-signal" }, - // { label: "Manage Permissions", slug: "how-to-guides/builders/manage-permissions" }, // { label: "Delegate Emission Streams", slug: "how-to-guides/builders/delegate-emission-streams" }, { label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" }, { label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" }, diff --git a/src/content/docs/how-to-guides/builders/manage-permissions.mdx b/src/content/docs/how-to-guides/builders/manage-permissions.mdx index cb8a449..9d8ecb5 100644 --- a/src/content/docs/how-to-guides/builders/manage-permissions.mdx +++ b/src/content/docs/how-to-guides/builders/manage-permissions.mdx @@ -1,278 +1,263 @@ --- title: Manage Permissions -description: Step-by-step guide to creating, editing, and managing permissions in Torus's recursive delegation system. +description: Step-by-step guide to creating and managing permissions in the Torus portal. --- import { Steps, Aside, CardGrid, - Card, - Tabs, - TabItem + Card } from "@astrojs/starlight/components"; + +import ClickableImage from '/src/components/ClickableImage.astro'; import RedText from '/src/components/RedText.astro'; -In this guide, we'll walk through **managing permissions** in Torus's recursive delegation system. -Permissions enable fine-grained control over emission distribution and capability access between agents. +In this guide, we'll walk through **managing permissions** in the Torus portal. +Permissions control access to network resources and enable economic coordination between agents. + +## Permission Types + +Torus has two distinct permission types that serve different purposes: + +**Capability Permissions**: Control access to specific agent endpoints and APIs +**Emission Permissions**: Enable economic coordination by delegating token emission streams + +Each type has different creation workflows but can be managed through the same interface. + #### What we will accomplish -- Create capability and emission permissions -- Configure delegation terms and constraints -- Edit and revoke existing permissions -- Understand revocation and enforcement mechanisms +- [Create capability permissions](#create-capability-permission) +- [Create emission permissions](#create-emission-permission) +- [Manage existing permissions](#manage-existing-permissions) ## Prerequisites - You must have a registered agent that can delegate permissions. - - - Know the agent addresses you want to delegate permissions to. + You must have a registered agent on Torus. + Follow the [agent registration guide](https://docs.torus.network/how-to-guides/builders/register-an-agent/) if needed. - Ensure sufficient TORUS for transaction fees. + Ensure you have enough TORUS to cover permission creation and transaction fees. + + + For emission permissions, you must have incoming emission streams to delegate. This means either being a Root Agent with stake directed to you, or receiving emissions from other agents. -## Permission Types +## Create Capability Permission - - - -**Purpose**: Grant access to specific agent endpoints or namespaces -**Use Cases**: API access, service delegation, resource sharing - -**Example**: Allow Agent B to access Agent A's memory storage API - - - - -**Purpose**: Delegate portions of emission streams (token flows) -**Use Cases**: Hiring agents, revenue sharing, economic coordination - -**Example**: Agent A delegates 20% of staking rewards to Agent B - - - - -## Create a Permission +Capability permissions control access to specific agent endpoints and APIs. -1. **Visit the [Torus Portal](https://portal.torus.network/)** - Navigate to **Permissions Management** → **Create Permission**. - -2. **Connect your wallet** - Ensure you're connected as the delegating agent. - -3. **Choose permission type** - Select either **Capability** or **Emission** permission from the dropdown. - -4. **Configure permission details based on type** - -5. **Set revocation terms** - -6. **Configure enforcement** (Optional) - -7. **Review permission contract** - -8. **Submit permission** - -9. **Verify creation** +1. **Navigate to [Create Permissions tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/capability)** + It can be found in the left-hand navigation bar of the [Torus Portal](https://portal.torus.network). + +2. **Connect your Wallet** + Click the **Connect Wallet** button at the top right and select your Torus wallet that owns the agent with the permissions you want to create. + +3. **Fill the form** + ```md + # Recipient + The agent that will receive the permission. + + # Capability Path + The path to the agent endpoint or API. + + # Duration + - **Indefinite**: Permission remains valid indefinitely. + - **Until Block**: Permission expires at a specific block. + + # Revocation Terms + - **Irrevocable**: Cannot be revoked. + - **Revocable by Delegator**: Only the delegator can revoke. + - **Revocable by Arbiters**: Can be revoked by arbiters after + a vote threshold set by the delegator. + - **After Block**: Can only be revoked after a specific block. + ``` + + +4. **Select Create Permission** + Click on the **Create Permission** tab or button. + +5. **Choose Capability Permission Type** + Select **Capability Permission** from the permission type options. + +6. **Configure Capability Access** + Fill in the capability permission details: + - **Target Agent**: Specify which agent will receive access + - **Capability Path**: Define the specific capability path (e.g., `agent.alice.store.post`) + - **Access Level**: Set the level of access granted + - **Duration**: Set expiration time if applicable + + + +7. **Review and Confirm** + Double-check all details and click **Create Permission** to confirm. + +8. **Transaction Confirmation** + Confirm the transaction in your wallet to complete the capability permission creation. -### Configuring Capability Permissions - -For capability permissions, configure these details: - -**Namespace Path**: Enter the specific capability path -- Format: `agent...` -- Example: `agent.alice.memory.twitter.post` - -**Recipient**: Agent address that will receive access - -**Duration**: Set permission lifespan -- **Indefinite**: Permission lasts until manually revoked -- **Fixed Term**: Specify end date/block number -- **Conditional**: Based on specific triggers - -**Constraints**: Optional usage limitations -- Rate limits (calls per hour/day) -- Access windows (specific times) -- Usage quotas - -### Configuring Emission Permissions - -For emission permissions, configure these details: - -**Stream Selection**: Choose which emission streams to delegate -- Staking rewards -- Delegation fees -- Specific revenue streams - -**Allocation Type**: -- **Percentage**: Delegate X% of selected streams -- **Fixed Amount**: Delegate specific TORUS amount per period - -**Recipient**: Agent address that will receive emissions - -**Duration**: Set delegation period -- Ongoing until revoked -- Fixed term (blocks/time) -- Performance-based triggers - -### Setting Revocation Terms -Configure how the permission can be terminated: +## Create Emission Permission -- **Revocable**: You can cancel anytime -- **Irrevocable**: Cannot be cancelled (use carefully) -- **Conditional**: Auto-revoke based on conditions - -### Configuring Enforcement - -Set third-party governance authority (Optional): -- DAO enforcement for disputes -- Multi-sig requirements -- Community arbitration - -### Review and Submit - -Before submission, verify all details: -- Delegator and recipient addresses -- Scope and limitations -- Duration and revocation terms -- Associated costs - -## Managing Permissions - -### View Active Permissions - -Track your delegated permissions in the Torus Portal: -- **Outgoing**: Permissions you've granted to others -- **Incoming**: Permissions others have granted to you -- **Status**: Active, expired, revoked permissions - -### Edit Permissions - -For permissions you've created: +Emission permissions enable economic coordination by delegating portions of your token emission streams. -1. Navigate to **Permissions Management** → **Edit Permission** -2. Select the permission to modify -3. Update allowed parameters (within original constraints) -4. Submit changes on-chain +1. **Navigate to [Torus Portal](https://portal.torus.network)** + Go to the Torus Portal and connect your wallet. + +2. **Access Control Space** + Click on the **Control Space** tab in the sidebar. + +3. **Select Create Permission** + Click on the **Create Permission** tab or button. + +4. **Choose Emission Permission Type** + Select **Emission Permission** from the permission type options. + +5. **Configure Emission Delegation** + Set up the emission delegation parameters: + - **Target Agent**: Specify which agent will receive emissions + - **Allocation Type**: Choose between stream percentage or fixed amount + - **Amount/Percentage**: Set the delegation amount or percentage + - **Distribution Control**: Choose when tokens are distributed + + + +6. **Set Distribution Parameters** + Configure how and when delegated tokens are distributed: + - For **Manual**: No additional configuration needed + - For **Automatic**: Set accumulation threshold + - For **AtBlock**: Specify target block number + - For **Interval**: Set block interval frequency + +7. **Review Economic Impact** + Carefully review the economic implications: + - Total tokens being delegated + - Impact on your remaining emission streams + - Distribution timing and frequency + +8. **Confirm Delegation** + Click **Create Emission Permission** to proceed. + +9. **Transaction Confirmation** + Confirm the transaction in your wallet. Note that emission permissions may require higher transaction fees due to complexity. -### Revoke Permissions +## Manage Existing Permissions -To cancel a revocable permission: +Both capability and emission permissions can be managed through the same interface with type-specific options. -1. Find the permission in your management dashboard -2. Select **Revoke Permission** -3. Confirm revocation (immediate effect) -4. Sign transaction to execute on-chain +1. **Navigate to Control Space** + From the [Torus Portal](https://portal.torus.network), go to the **Control Space** section. + +2. **View Your Permissions** + Browse your permissions organized by type: + - **Capability Permissions**: Shows endpoint access you've granted/received + - **Emission Permissions**: Shows token delegations you've created/received + +3. **Select Permission to Manage** + Click on the specific permission you want to modify from either category. + +4. **Choose Management Action** + Available actions depend on permission type: + + **For Capability Permissions:** + - **Modify Access**: Update capability paths or access levels + - **Extend/Reduce Duration**: Adjust expiration times + - **Revoke Access**: Remove permission entirely + + **For Emission Permissions:** + - **Adjust Allocation**: Modify percentage or fixed amounts + - **Change Distribution**: Update distribution control settings + - **Pause/Resume**: Temporarily halt emissions without revoking + - **Revoke Delegation**: Permanently end emission sharing + + + +5. **Configure Changes** + Make your desired modifications: + - For simple changes: Update parameters directly + - For complex changes: May require creating new permission and revoking old one + - For emission changes: Handle any accumulated undistributed tokens + +6. **Review Impact** + Before confirming: + - **Capability Changes**: Verify affected agents can still access needed endpoints + - **Emission Changes**: Review economic impact on all parties involved + +7. **Complete Transaction** + Click the appropriate action button and confirm the management transaction in your wallet. + + -## Advanced Configuration - -### Recursive Permissions - -Create permission chains where recipients can further delegate: - -- **Enable sub-delegation**: Allow recipients to delegate portions -- **Set depth limits**: Maximum delegation chain length -- **Inheritance rules**: How constraints pass down the chain - -### Conditional Permissions - -Set up smart permissions that trigger based on conditions: - -- **Performance metrics**: Delegate based on agent performance -- **Time-based**: Activate during specific periods -- **Event-driven**: Trigger on blockchain events - -## Best Practices - -### Security Considerations - -- **Principle of least privilege**: Grant minimum necessary permissions -- **Regular audits**: Review and clean up unused permissions -- **Test with small amounts**: Start with small emission delegations - -### Economic Efficiency - -- **Batch operations**: Group related permissions to save gas -- **Monitor performance**: Track ROI on emission delegations -- **Set reasonable terms**: Balance flexibility with security - -### Delegation Strategy - -- **Clear documentation**: Maintain records of permission purposes -- **Communication**: Coordinate with recipients about expectations -- **Gradual scaling**: Increase delegation scope based on proven success - -## Troubleshooting - -### Permission Creation Fails - -**Common issues:** -- Insufficient balance for transaction fees -- Invalid recipient agent address -- Namespace path doesn't exist (for capabilities) -- Attempting to delegate more than available (for emissions) - -### Permission Not Working - -**Check that:** -- Permission is active and not expired -- Recipient is using correct namespace path -- No conflicting constraints or rate limits -- Blockchain confirmation completed - -### Revocation Issues - -**Verify:** -- Permission was created as revocable -- You're the original delegator -- No outstanding enforcement claims - ## What's Next? -After managing permissions, you can: - -- **Monitor usage**: Track how recipients use delegated permissions -- **Optimize delegation**: Adjust terms based on performance -- **Scale coordination**: Build complex multi-agent workflows -- **Analyze economics**: Review emission delegation ROI - -## Support and Resources - -For help with permission management: +After successfully managing your permissions, you can: -- [Torus Community Discord](https://discord.gg/torus) -- [Permission System Documentation](https://docs.torus.network/explanations/v05/permissions/) +- **Explore capability management**: Learn about [managing capabilities](https://docs.torus.network/how-to-guides/builders/manage-capabilities/) +- **Set up agent services**: Use your permissions in an [agent server](https://docs.torus.network/how-to-guides/builders/setup-agent-server/) +- **Connect with other agents**: Learn about [agent client](https://docs.torus.network/how-to-guides/builders/setup-agent-client/) integration +- **Create demand signals**: Signal demand for specific capabilities with [create a signal](https://docs.torus.network/how-to-guides/builders/create-signal/) -#### Related Topics - - - - Deep dive into architecture - - - Economic coordination mechanisms - - \ No newline at end of file +For more technical details about how permissions work, see the [permission system explanation](https://docs.torus.network/explanations/v05/permissions/). \ No newline at end of file diff --git a/src/content/docs/how-to-guides/start-here.mdx b/src/content/docs/how-to-guides/start-here.mdx index 0f1ffcb..71c376d 100644 --- a/src/content/docs/how-to-guides/start-here.mdx +++ b/src/content/docs/how-to-guides/start-here.mdx @@ -40,7 +40,7 @@ If you're developing tools, services, or integrations on Torus: - [Setup Agent Server](https://docs.torus.network/how-to-guides/builders/setup-agent-server/) - [Setup Agent Client](https://docs.torus.network/how-to-guides/builders/setup-agent-client/) - [Manage Capabilities](https://docs.torus.network/how-to-guides/builders/manage-capabilities/) -- Manage Permissions _(coming soon)_ +- [Manage Permissions](https://docs.torus.network/how-to-guides/builders/manage-permissions/) - Delegate Emission Streams _(coming soon)_ ---