Skip to content

Commit 959fbce

Browse files
SipherSipher
committed
Refactor explanations and guides by updating capability and control space documentation for clarity and improved navigation
1 parent 15daf03 commit 959fbce

File tree

6 files changed

+287
-8
lines changed

6 files changed

+287
-8
lines changed

‎astro.config.mjs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,6 @@ export default defineConfig({
5151
{ label: "Demand Signaling", slug: "explanations/builders/demand-signaling" },
5252
{ label: "Agent Server", slug: "explanations/builders/agent-server" },
5353
{ label: "Agent Client", slug: "explanations/builders/agent-client" },
54-
{ label: "Control Space", slug: "explanations/builders/control-space" },
55-
{ label: "Capability Permissions", slug: "explanations/builders/capability-permissions" },
5654
],
5755
},
5856
{
@@ -69,9 +67,11 @@ export default defineConfig({
6967
label: "System",
7068
collapsed: true,
7169
items: [
70+
{ label: "Control Space", slug: "explanations/system/control-space" },
7271
{ label: "Permission System", slug: "explanations/system/permission-system" },
73-
{ label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" },
7472
{ label: "Emission Permissions", slug: "explanations/system/emission-permissions" },
73+
{ label: "Capability Permissions", slug: "explanations/system/capability-permissions" },
74+
{ label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" },
7575
],
7676
},
7777
{ label: "Concepts & Terminology", slug: "explanations/concepts-terminology" },
@@ -116,6 +116,7 @@ export default defineConfig({
116116
label: "System",
117117
collapsed: true,
118118
items: [
119+
{ label: "Create Permission", slug: "how-to-guides/system/create-permission" },
119120
{ label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" },
120121
{ label: "Create Emission Permission", slug: "how-to-guides/system/create-emission-permission" },
121122
{ label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" },

src/content/docs/explanations/builders/capability-permissions.mdx renamed to src/content/docs/explanations/system/capability-permissions.mdx

File renamed without changes.

src/content/docs/explanations/builders/control-space.mdx renamed to src/content/docs/explanations/system/control-space.mdx

File renamed without changes.

‎src/content/docs/explanations/table-of-contents.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,6 @@ Understanding how agent systems work within Torus:
3838
- [Demand Signaling](https://docs.torus.network/explanations/builders/demand-signaling/) — Capability coordination and economic incentives
3939
- [Agent Server](https://docs.torus.network/explanations/builders/agent-server/) — API architecture, authentication, and capability sharing
4040
- [Agent Client](https://docs.torus.network/explanations/builders/agent-client/) — Communication patterns and authentication flow
41-
- [Control Space](https://docs.torus.network/explanations/builders/control-space/) — Foundational permission and capability framework
42-
- [Capability Permissions](https://docs.torus.network/explanations/builders/capability-permissions/) — Fine-grained access control for agent endpoints
4341

4442
---
4543

@@ -58,9 +56,11 @@ Understanding governance and leadership systems:
5856

5957
Core system components and mechanisms:
6058

59+
- [Control Space](https://docs.torus.network/explanations/system/control-space/) — Foundational permission and capability framework
6160
- [Permission System](https://docs.torus.network/explanations/system/permission-system/) — How agents interact and delegate authority
62-
- [Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/) — Specific capability delegation mechanisms
6361
- [Emission Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled
62+
- [Capability Permissions](https://docs.torus.network/explanations/system/capability-permissions/) — Fine-grained access control for agent endpoints
63+
- [Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/) — Specific capability delegation mechanisms
6464

6565
---
6666

‎src/content/docs/how-to-guides/system/create-permission.mdx‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: Manage Permissions
3+
description: Step-by-step guide to creating, editing, and managing permissions in Torus's recursive delegation system.
4+
---
5+
6+
import {
7+
Steps,
8+
Aside,
9+
CardGrid,
10+
Card,
11+
Tabs,
12+
TabItem
13+
} from "@astrojs/starlight/components";
14+
15+
In this guide, we'll walk through **creating permissions** in Torus's recursive delegation system.
16+
Permissions enable fine-grained control over emission distribution and capability access between agents.
17+
18+
#### What we will accomplish
19+
20+
- Create capability and emission permissions
21+
- Configure delegation terms and constraints
22+
- Understand revocation and enforcement mechanisms
23+
24+
<Aside>
25+
⏱️ **Estimated time to complete this guide: 15 minutes**
26+
</Aside>
27+
28+
## Prerequisites
29+
30+
<CardGrid>
31+
<Card title="Registered Agent" icon="seti:license">
32+
You must have a registered agent that can delegate permissions.
33+
</Card>
34+
<Card title="Target Recipients" icon="seti:users">
35+
Know the agent addresses you want to delegate permissions to.
36+
</Card>
37+
<Card title="Torus Balance" icon="seti:shell">
38+
Ensure sufficient TORUS for transaction fees.
39+
</Card>
40+
</CardGrid>
41+
42+
## Permission Types
43+
44+
<Tabs>
45+
<TabItem label="Capability Permissions">
46+
47+
**Purpose**: Grant access to specific agent endpoints or namespaces
48+
**Use Cases**: API access, service delegation, resource sharing
49+
50+
**Example**: Allow Agent B to access Agent A's memory storage API
51+
52+
</TabItem>
53+
<TabItem label="Emission Permissions">
54+
55+
**Purpose**: Delegate portions of emission streams (token flows)
56+
**Use Cases**: Hiring agents, revenue sharing, economic coordination
57+
58+
**Example**: Agent A delegates 20% of staking rewards to Agent B
59+
60+
</TabItem>
61+
</Tabs>
62+
63+
## Create a Permission
64+
65+
<Steps>
66+
67+
1. **Visit the [Torus Portal](https://portal.torus.network/)**
68+
Navigate to **Permissions Management** → **Create Permission**.
69+
70+
2. **Connect your wallet**
71+
Ensure you're connected as the delegating agent.
72+
73+
3. **Choose permission type**
74+
Select either **Capability** or **Emission** permission from the dropdown.
75+
76+
4. **Configure permission details based on type**
77+
78+
5. **Set revocation terms**
79+
80+
6. **Configure enforcement** (Optional)
81+
82+
7. **Review permission contract**
83+
84+
8. **Submit permission**
85+
86+
9. **Verify creation**
87+
88+
</Steps>
89+
90+
### Configuring Capability Permissions
91+
92+
For capability permissions, configure these details:
93+
94+
**Namespace Path**: Enter the specific capability path
95+
- Format: `agent.<agent_name>.<endpoint>.<method>`
96+
- Example: `agent.alice.memory.twitter.post`
97+
98+
**Recipient**: Agent address that will receive access
99+
100+
**Duration**: Set permission lifespan
101+
- **Indefinite**: Permission lasts until manually revoked
102+
- **Fixed Term**: Specify end date/block number
103+
- **Conditional**: Based on specific triggers
104+
105+
**Constraints**: Optional usage limitations
106+
- Rate limits (calls per hour/day)
107+
- Access windows (specific times)
108+
- Usage quotas
109+
110+
### Configuring Emission Permissions
111+
112+
For emission permissions, configure these details:
113+
114+
**Stream Selection**: Choose which emission streams to delegate
115+
- Staking rewards
116+
- Delegation fees
117+
- Specific revenue streams
118+
119+
**Allocation Type**:
120+
- **Percentage**: Delegate X% of selected streams
121+
- **Fixed Amount**: Delegate specific TORUS amount per period
122+
123+
**Recipient**: Agent address that will receive emissions
124+
125+
**Duration**: Set delegation period
126+
- Ongoing until revoked
127+
- Fixed term (blocks/time)
128+
- Performance-based triggers
129+
130+
### Setting Revocation Terms
131+
132+
Configure how the permission can be terminated:
133+
134+
- **Revocable**: You can cancel anytime
135+
- **Irrevocable**: Cannot be cancelled (use carefully)
136+
- **Conditional**: Auto-revoke based on conditions
137+
138+
### Configuring Enforcement
139+
140+
Set third-party governance authority (Optional):
141+
- DAO enforcement for disputes
142+
- Multi-sig requirements
143+
- Community arbitration
144+
145+
### Review and Submit
146+
147+
Before submission, verify all details:
148+
- Delegator and recipient addresses
149+
- Scope and limitations
150+
- Duration and revocation terms
151+
- Associated costs
152+
153+
## Managing Permissions
154+
155+
### View Active Permissions
156+
157+
Track your delegated permissions in the Torus Portal:
158+
- **Outgoing**: Permissions you've granted to others
159+
- **Incoming**: Permissions others have granted to you
160+
- **Status**: Active, expired, revoked permissions
161+
162+
### Edit Permissions
163+
164+
For permissions you've created:
165+
166+
<Steps>
167+
168+
1. Navigate to **Permissions Management** → **Edit Permission**
169+
2. Select the permission to modify
170+
3. Update allowed parameters (within original constraints)
171+
4. Submit changes on-chain
172+
173+
</Steps>
174+
175+
### Revoke Permissions
176+
177+
To cancel a revocable permission:
178+
179+
<Steps>
180+
181+
1. Find the permission in your management dashboard
182+
2. Select **Revoke Permission**
183+
3. Confirm revocation (immediate effect)
184+
4. Sign transaction to execute on-chain
185+
186+
</Steps>
187+
188+
## Advanced Configuration
189+
190+
### Recursive Permissions
191+
192+
Create permission chains where recipients can further delegate:
193+
194+
- **Enable sub-delegation**: Allow recipients to delegate portions
195+
- **Set depth limits**: Maximum delegation chain length
196+
- **Inheritance rules**: How constraints pass down the chain
197+
198+
### Conditional Permissions
199+
200+
Set up smart permissions that trigger based on conditions:
201+
202+
- **Performance metrics**: Delegate based on agent performance
203+
- **Time-based**: Activate during specific periods
204+
- **Event-driven**: Trigger on blockchain events
205+
206+
## Best Practices
207+
208+
### Security Considerations
209+
210+
- **Principle of least privilege**: Grant minimum necessary permissions
211+
- **Regular audits**: Review and clean up unused permissions
212+
- **Test with small amounts**: Start with small emission delegations
213+
214+
### Economic Efficiency
215+
216+
- **Batch operations**: Group related permissions to save gas
217+
- **Monitor performance**: Track ROI on emission delegations
218+
- **Set reasonable terms**: Balance flexibility with security
219+
220+
### Delegation Strategy
221+
222+
- **Clear documentation**: Maintain records of permission purposes
223+
- **Communication**: Coordinate with recipients about expectations
224+
- **Gradual scaling**: Increase delegation scope based on proven success
225+
226+
## Troubleshooting
227+
228+
### Permission Creation Fails
229+
230+
**Common issues:**
231+
- Insufficient balance for transaction fees
232+
- Invalid recipient agent address
233+
- Namespace path doesn't exist (for capabilities)
234+
- Attempting to delegate more than available (for emissions)
235+
236+
### Permission Not Working
237+
238+
**Check that:**
239+
- Permission is active and not expired
240+
- Recipient is using correct namespace path
241+
- No conflicting constraints or rate limits
242+
- Blockchain confirmation completed
243+
244+
### Revocation Issues
245+
246+
**Verify:**
247+
- Permission was created as revocable
248+
- You're the original delegator
249+
- No outstanding enforcement claims
250+
251+
## What's Next?
252+
253+
After creating permissions, you can:
254+
255+
- **Monitor usage**: Track how recipients use delegated permissions
256+
- **Optimize delegation**: Adjust terms based on performance
257+
- **Scale coordination**: Build complex multi-agent workflows
258+
- **Analyze economics**: Review emission delegation ROI
259+
260+
## Support and Resources
261+
262+
For help with permission management:
263+
264+
- [Torus Community Discord](https://discord.gg/torus)
265+
266+
<Aside type="tip" title="Want to Learn More?">
267+
See the [Permission System Documentation](https://docs.torus.network/explanations/system/permission-system/) for technical details.
268+
</Aside>
269+
270+
#### Related Topics
271+
272+
<CardGrid>
273+
<Card title="Permission System" icon="seti:config">
274+
<a href="/explanations/system/permission-system">Deep dive into architecture</a>
275+
</Card>
276+
<Card title="Emission Permissions" icon="seti:shell">
277+
<a href="/explanations/system/emission-permissions">Economic coordination mechanisms</a>
278+
</Card>
279+
</CardGrid>

‎src/content/docs/how-to-guides/table-of-contents.mdx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ If you're developing tools, services, or integrations on Torus:
4444
---
4545

4646
## For Root Goal-Setters and Leaders
47-
_Leading new swarms or driving protocol changes_
4847

4948
If you're pioneering new goals or submitting DAO proposals:
5049

@@ -55,10 +54,10 @@ If you're pioneering new goals or submitting DAO proposals:
5554
---
5655

5756
## System Management
58-
_Working with permissions, delegation, and system mechanics_
5957

6058
If you're managing permissions and system-level coordination:
6159

60+
- [Create Permission](https://docs.torus.network/how-to-guides/system/create-permission/)
6261
- [Create Capability Permission](https://docs.torus.network/how-to-guides/system/create-capability-permission/)
6362
- [Create Emission Permission](https://docs.torus.network/how-to-guides/system/create-emission-permission/)
6463
- [Manage Permissions](https://docs.torus.network/how-to-guides/system/manage-permissions/)

0 commit comments

Comments
 (0)