Skip to content

Commit 66f3076

Browse files
Sipherrad2520
andauthored
Small fixes before official release (#37)
* Refactor table of contents to group system-related guides under a new "System" section for better organization and clarity * Remove redundant notes from the table of contents to streamline guidance on proposal and permission creation processes * Update index.mdx * Refactor explanations and guides by updating capability and control space documentation for clarity and improved navigation * Enhance system documentation by adding and reorganizing sections on permissions and capabilities in explanations and guides * Update permission terminology in docs from "emission" to "stream" for consistency across the system and user guides * Refactor styling to adopt orange themes and enhance component utilities in Tailwind CSS for improved visual consistency * Remove deprecated "Create Permission" guide from system documentation and update table of contents accordingly for clarity --------- Co-authored-by: rad2520 <[email protected]>
1 parent 9b5ead5 commit 66f3076

File tree

13 files changed

+552
-45
lines changed

13 files changed

+552
-45
lines changed

astro.config.mjs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export default defineConfig({
4040
{ label: "Control Space", slug: "explanations/system/control-space" },
4141
{ label: "Permission System", slug: "explanations/system/permission-system" },
4242
{ label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" },
43-
{ label: "Emission Permissions", slug: "explanations/system/emission-permissions" },
43+
{ label: "Stream Permissions", slug: "explanations/system/stream-permissions" },
4444
{ label: "Capability Permissions", slug: "explanations/system/capability-permissions" },
4545
],
4646
},
@@ -85,9 +85,9 @@ export default defineConfig({
8585
label: "System",
8686
collapsed: true,
8787
items: [
88-
{ label: "Create Permission", slug: "how-to-guides/system/create-permission" },
88+
8989
{ label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" },
90-
{ label: "Create Emission Permission", slug: "how-to-guides/system/create-emission-permission" },
90+
{ label: "Create Stream Permission", slug: "how-to-guides/system/create-stream-permission" },
9191
{ label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" },
9292
],
9393
},

src/content/docs/explanations/builders/agent-managing.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Before de-registering an agent, you must:
4848

4949
De-registration results in permanent loss of:
5050
- **All registered namespaces** — all capability paths will be deleted
51-
- **Ability to create new delegations** — namespace and emission delegation capabilities are revoked
51+
- **Ability to create new delegations** — namespace and stream delegation capabilities are revoked
5252
- **Delegated permissions** — all permissions granted to/from your agent will be revoked
5353
- **Agent identity** — the agent is completely removed from the network
5454

src/content/docs/explanations/builders/demand-signaling.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Demand Signaling
3-
description: Understanding how agents coordinate specialization through demand signals and emission delegation.
3+
description: Understanding how agents coordinate specialization through demand signals and stream delegation.
44
---
55

66
import {
@@ -13,7 +13,7 @@ import {
1313
The [Create Signal feature on the Portal](https://portal.torus.network/signals/create-signal) allows agents to express in a technical and economical way
1414
their demand for specialized capabilities from other agents.
1515

16-
Standard agents are looking for opportunities to receive emission delegations by providing specialized capabilities.
16+
Standard agents are looking for opportunities to receive stream delegations by providing specialized capabilities.
1717
This means, you can define a problem and increase interest in solving it by proposing an allocation of your own emissions.
1818

1919
For example, if you have an agent specializing on finding predictions for the swarm memory and your accuracy and rewards suffer by failing to filter out irony,

src/content/docs/explanations/system/permission-system.mdx

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Permission System Architecture
3-
description: Comprehensive guide to Torus's recursive delegation system, emission permissions, and control distribution mechanisms.
3+
description: Comprehensive guide to Torus's recursive delegation system, stream permissions, and control distribution mechanisms.
44
---
55

66
import { CardGrid, LinkCard, Aside, Tabs, TabItem } from "@astrojs/starlight/components";
@@ -35,7 +35,8 @@ The system supports three fundamental permission types that enable comprehensive
3535

3636
```rust
3737
pub enum PermissionScope {
38-
Emission(EmissionScope), // Token delegation permissions
38+
Emission(EmissionScope), // Stream delegation permissions
39+
3940
Curator(CuratorScope), // Governance function delegation
4041
Capability(CapabilityScope), // Off-chain service access control
4142
}

src/content/docs/explanations/system/recursive-delegation.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ At each delegation step, permission's can be
2121
- granularly partitioned into smaller permissions until reaching the atomic level
2222
- paired with a new constraint, accumulating a constraint stack throughout the delegation path.
2323

24-
This applies to the capability, emission and curator permission type.
24+
This applies to the capability, stream and curator permission type.
2525

2626
### Core Functions
2727

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Stream Permissions
3+
description: Complete guide to stream permissions, stream delegation, and economic coordination mechanisms in Torus.
4+
---
5+
6+
<Aside type="note" title="Version notice">
7+
This version is based on the Torus v0.6 and is expected to change with the Torus v1.
8+
</Aside>
9+
10+
import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";
11+
12+
Stream permissions are the core tool and mechanism for economic incentives on Torus, enabling agents to compose and delegate portions of
13+
their incoming emission streams (token flows) to other agents with flexible control.
14+
This enables agents to hire other agents and form economic group structures.
15+
16+
## Stream Permission System
17+
18+
### Stream-Based Emission Model
19+
20+
The emission system preserves **stream identity** through delegation chains via unique `StreamId` identifiers.
21+
Each stream represents a distinct emission source (staking returns, delegation fees),
22+
enabling complete traceability of token flow from source to final recipients.
23+
24+
### Allocation Mechanisms
25+
26+
Stream permissions support two distinct allocation paradigms:
27+
28+
#### Stream Allocations (Percentage-Based)
29+
30+
Stream allocations enable agents to delegate specific percentages of incoming emissions from particular streams.
31+
32+
**Stream Allocation Characteristics:**
33+
- **Granular Control**: Different streams can have different delegation percentages (0-100%)
34+
- **Safety Constraints**: Total allocated percentage per stream cannot exceed 100%
35+
- **Dynamic Processing**: Emissions are intercepted and redirected during distribution
36+
- **Recursive Support**: Delegated streams maintain their identity through recursive delegation chains
37+
38+
39+
#### Fixed Amount Allocations
40+
41+
Fixed amount allocations allow you to set aside specific token quantities for delegation:
42+
43+
**Fixed Amount Characteristics:**
44+
- **Upfront Reservation**: Tokens are reserved from your account at permission creation
45+
- **One-time Distribution**: Can only be executed once (manually or at a specific block)
46+
- **Distribution Constraints**: Limited to manual trigger or specific block execution
47+
- **Safety Guarantee**: Reserved tokens cannot be double-spent or allocated elsewhere
48+
49+
### Distribution Control Mechanisms
50+
51+
The system provides four distribution control patterns that determine when and how delegated tokens are transferred:
52+
53+
##### Manual Distribution
54+
**Manual Distribution** requires explicit execution by the recipient:
55+
56+
- **Recipient Control**: Recipient determines when to claim accumulated tokens
57+
- **Flexibility**: Allows strategic timing of token distribution
58+
- **Gas Efficiency**: Batches multiple accumulations into single distribution
59+
60+
##### Automatic Distribution
61+
**Automatic Distribution** triggers when accumulated amounts reach a threshold:
62+
63+
- **Threshold-Based**: Automatically executes when accumulated amount exceeds threshold
64+
- **Predictable**: Ensures regular distribution without manual intervention
65+
- **Efficient**: Reduces the need for manual monitoring
66+
67+
##### Block-Based Distribution
68+
**AtBlock Distribution** executes once at a specific block:
69+
70+
- **Scheduled**: Executes at predetermined block height
71+
- **One-time**: Single execution at specified block
72+
- **Predictable**: Known execution timing
73+
74+
##### Interval Distribution
75+
**Interval Distribution** executes periodically at fixed intervals:
76+
77+
- **Periodic**: Regular execution at specified block intervals
78+
- **Automated**: No manual intervention required
79+
- **Consistent**: Predictable distribution schedule
80+
81+
---
82+
### Emission Accumulation Process
83+
84+
The accumulation mechanism efficiently processes emissions through a multi-stage pipeline:
85+
86+
1. **Interception**: When agents receive emissions, the system checks for active permissions
87+
2. **Stream Matching**: Permissions are filtered by stream ID and allocation type
88+
3. **Percentage Extraction**: For stream allocations, the specified percentage is extracted
89+
4. **Storage**: Accumulated amounts are stored with agent-stream-permission indexing
90+
5. **Distribution Triggers**: Various conditions trigger automatic distribution

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Core system components and mechanisms:
2525
- [Control Space](https://docs.torus.network/explanations/system/control-space/) — Foundational permission and capability framework
2626
- [Permission System](https://docs.torus.network/explanations/system/permission-system/) — How agents interact and delegate authority
2727
- [Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/) — Specific capability delegation mechanisms
28-
- [Emission Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled
28+
- [Stream Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled
2929
- [Capability Permissions](https://docs.torus.network/explanations/system/capability-permissions/) — Fine-grained access control for agent endpoints
3030

3131
---

src/content/docs/how-to-guides/builders/manage-your-agent.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ and ensures your agent represents your current capabilities and offerings.
103103

104104
**You will permanently lose:**
105105
- <RedText variant="light">All registered namespaces</RedText> — all capability paths will be deleted
106-
- <RedText variant="light">Ability to create new namespace or emission delegations</RedText>
106+
- <RedText variant="light">Ability to create new namespace or stream delegations</RedText>
107107
- <RedText variant="light">Delegated permissions</RedText> — all permissions granted to/from your agent will be revoked
108108
- Agent name — you CAN reuse this name if you <RedText variant="light">re-register</RedText> later
109109

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Create Stream Permission
3+
description: Step-by-step guide to creating stream permissions to delegate token emission streams to other agents.
4+
---
5+
6+
import {
7+
Steps,
8+
Aside,
9+
CardGrid,
10+
Card
11+
} from "@astrojs/starlight/components";
12+
13+
import ClickableImage from '/src/components/ClickableImage.astro';
14+
import RedText from '/src/components/RedText.astro';
15+
16+
In this guide, we'll walk through **creating stream permissions** in the Torus portal.
17+
Stream permissions enable economic coordination by delegating portions of your token emission streams to other agents.
18+
19+
## Why Create Stream Permissions?
20+
21+
Stream permissions allow you to:
22+
- **Hire agents**: Pay other agents for services using your emission streams
23+
- **Create incentives**: Reward agents based on performance or contributions
24+
- **Economic coordination**: Build complex multi-agent workflows with token flows
25+
26+
#### What we will accomplish
27+
28+
- [Create stream permissions](#create-stream-permission)
29+
30+
<Aside>
31+
⏱️ **Estimated time to complete this guide: 5 minutes**
32+
</Aside>
33+
34+
## Prerequisites
35+
36+
<CardGrid>
37+
<Card title="Registered Agent" icon="seti:license">
38+
You must have a registered agent on Torus.
39+
Follow the [agent registration guide](https://docs.torus.network/how-to-guides/builders/register-an-agent/) if needed.
40+
</Card>
41+
<Card title="Torus Balance" icon="seti:shell">
42+
Ensure you have enough TORUS to cover permission creation and transaction fees.
43+
</Card>
44+
<Card title="Active Emission Stream" icon="seti:pipeline">
45+
For stream 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.
46+
</Card>
47+
</CardGrid>
48+
49+
## Create Stream Permission
50+
51+
Stream permissions enable economic coordination by delegating portions of your token emission streams.
52+
53+
<Steps>
54+
55+
1. **Visit the [Create Stream Permission tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/stream)**
56+
It can be found in the left-hand navigation bar of the [Torus Portal](https://portal.torus.network).
57+
58+
2. **Connect your Wallet**
59+
Click the <RedText variant="light">**Connect Wallet**</RedText> button at the top right and select your Torus wallet that owns the agent with the permissions you want to create.
60+
61+
3. **Click on the Stream tab**
62+
Select the <RedText variant="light">**Stream** tab instead of the **Capability** tab</RedText> to create stream permissions.
63+
64+
4. **Fill the form**
65+
```md
66+
# Distribution Type
67+
- **Manual**: Recipient triggers distribution when needed
68+
- **Automatic**: Auto-distribute when threshold is reached
69+
- **At Block**: Execute once at specific block height
70+
- **Interval**: Execute periodically at fixed intervals
71+
72+
# Block Interval
73+
Number of blocks between periodic distributions
74+
(only shown for Interval distribution type)
75+
76+
# Duration Type
77+
- **Indefinite**: Permission remains valid indefinitely
78+
- **Until Block**: Permission expires at a specific block
79+
80+
# Revocation Type
81+
- **Irrevocable**: Cannot be revoked
82+
- **Revocable by Delegator**: Only the delegator can revoke
83+
- **Revocable by Arbiters**: Can be revoked by arbiters after
84+
a vote threshold set by the delegator
85+
- **After Block**: Can only be revoked after a specific block
86+
87+
# Streams
88+
- **Stream ID**: Identifier of the emission stream to delegate
89+
- **Percentage**: Percentage of that stream to delegate (0-100%)
90+
91+
# Recipient Accounts
92+
- **Account**: Wallet address of the recipient agent
93+
- **Weight**: Percentage weight for this recipient
94+
(distribution among multiple targets)
95+
96+
# Recipient Manager (Optional)
97+
Account authorized to manage recipients for this stream permission.
98+
Leave empty if no specific manager is required.
99+
100+
# Weight Setter (Optional)
101+
Account authorized to modify recipient weights for this stream permission.
102+
Leave empty if no specific weight setter is required.
103+
```
104+
105+
5. **Review and Confirm**
106+
Double-check all details and click <RedText variant="light">**Create Permission**</RedText> to confirm.
107+
Sign the transaction in your Wallet to finish the creation.
108+
109+
6. **All Done**
110+
Your Stream Permission is now delegated. You can check it in the [Management tab](https://portal.torus.network/permissions/manage-permission).
111+
</Steps>
112+
113+
## What's Next?
114+
115+
After creating your stream permission, you can:
116+
117+
- **Monitor performance**: Track how recipients use delegated emissions
118+
- **Adjust permissions**: Modify terms based on agent performance
119+
- **Scale coordination**: Build complex multi-agent economic workflows
120+
- **Manage permissions**: View and revoke permissions through the [manage permissions guide](https://docs.torus.network/how-to-guides/system/manage-permissions/)
121+
122+
<Aside type="tip" title="Want to Learn More?">
123+
For more technical details about stream permissions, see the [stream permissions explanation](https://docs.torus.network/explanations/system/stream-permissions/).
124+
</Aside>

0 commit comments

Comments
 (0)