Skip to content

Commit 5fc9ae2

Browse files
SipherSipher
authored
Merge branch 'main' into dev
2 parents 7209d75 + 9b5ead5 commit 5fc9ae2

File tree

7 files changed

+545
-1
lines changed

7 files changed

+545
-1
lines changed

‎astro.config.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ export default defineConfig({
8585
label: "System",
8686
collapsed: true,
8787
items: [
88+
8889
{ label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" },
8990
{ label: "Create Stream Permission", slug: "how-to-guides/system/create-stream-permission" },
9091
{ label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" },

‎src/content/docs/explanations/system/emission-permissions.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Emission Permissions
3+
description: Complete guide to emission 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.5 and is expected to change with the Torus v1.
8+
</Aside>
9+
10+
import { CardGrid, LinkCard, Aside, Tabs, TabItem } from "@astrojs/starlight/components";
11+
12+
Emission permissions are the core tool and mechanism for economic incentives on Torus, enabling agents to compose and delegate portions of their incoming emission streams (token flows) to other agents with flexible control. This enables agents to hire other agents and form economic group structures.
13+
14+
## Emission Permission System
15+
16+
Emission permissions are core tool and mechanism for economic incentives on Torus, enabling agents to compose and delegate portions of their incoming emission streams (token flows) to other agents with flexible control. This enables agents to hire other agents and form economic group structures.
17+
18+
### Stream-Based Emission Model
19+
20+
The emission system preserves **stream identity** through delegation chains via unique `StreamId` identifiers. Each stream represents a distinct emission source (staking returns, delegation fees), enabling complete traceability of token flow from source to final recipients.
21+
22+
### Allocation Mechanisms
23+
24+
Emission permissions support two distinct allocation paradigms:
25+
26+
#### Stream Allocations (Percentage-Based)
27+
28+
Stream allocations enable agents to delegate specific percentages of incoming emissions from particular streams.
29+
30+
**Stream Allocation Characteristics:**
31+
- **Granular Control**: Different streams can have different delegation percentages (0-100%)
32+
- **Safety Constraints**: Total allocated percentage per stream cannot exceed 100%
33+
- **Dynamic Processing**: Emissions are intercepted and redirected during distribution
34+
- **Recursive Support**: Delegated streams maintain their identity through recursive delegation chains
35+
36+
37+
#### Fixed Amount Allocations
38+
39+
Fixed amount allocations reserve specific token quantities from the delegator's account at permission creation:
40+
41+
```rust
42+
FixedAmount(1000) // Reserve 1000 TORUS
43+
```
44+
45+
**Fixed Amount Characteristics:**
46+
- **Upfront Reservation**: Tokens are reserved using the Currency trait's reserve mechanism
47+
- **One-time Distribution**: Can only be executed once (manually or at a specific block)
48+
- **Distribution Constraints**: Limited to `Manual` or `AtBlock` distribution controls
49+
- **Safety Guarantee**: Uses the reserve/unreserve pattern to prevent double-spending
50+
51+
### Distribution Control Mechanisms
52+
53+
The system provides four distribution control patterns that determine when and how delegated tokens are transferred:
54+
55+
```rust
56+
pub enum DistributionControl {
57+
Manual, // Recipient triggers distribution
58+
Automatic(Balance), // Auto-trigger at threshold
59+
AtBlock(BlockNumber), // Execute at specific block
60+
Interval(BlockNumber), // Execute every N blocks
61+
}
62+
```
63+
64+
<Tabs>
65+
<TabItem label="Manual Distribution">
66+
**Manual Distribution** requires explicit execution by the recipient:
67+
68+
```rust
69+
DistributionControl::Manual
70+
```
71+
72+
- **Recipient Control**: Recipient determines when to claim accumulated tokens
73+
- **Flexibility**: Allows strategic timing of token distribution
74+
- **Gas Efficiency**: Batches multiple accumulations into single distribution
75+
</TabItem>
76+
77+
<TabItem label="Automatic Distribution">
78+
**Automatic Distribution** triggers when accumulated amounts reach a threshold:
79+
80+
```rust
81+
DistributionControl::Automatic(5000) // Auto-distribute at 5000 TORUS
82+
```
83+
84+
- **Threshold-Based**: Automatically executes when accumulated amount exceeds threshold
85+
- **Predictable**: Ensures regular distribution without manual intervention
86+
- **Efficient**: Reduces the need for manual monitoring
87+
</TabItem>
88+
89+
<TabItem label="Block-Based Distribution">
90+
**AtBlock Distribution** executes once at a specific block:
91+
92+
```rust
93+
DistributionControl::AtBlock(1_000_000) // Execute at block 1,000,000
94+
```
95+
96+
- **Scheduled**: Executes at predetermined block height
97+
- **One-time**: Single execution at specified block
98+
- **Predictable**: Known execution timing
99+
</TabItem>
100+
101+
<TabItem label="Interval Distribution">
102+
**Interval Distribution** executes periodically at fixed intervals:
103+
104+
```rust
105+
DistributionControl::Interval(10_800) // Execute every 10,800 blocks (~24 hours)
106+
```
107+
108+
- **Periodic**: Regular execution at specified block intervals
109+
- **Automated**: No manual intervention required
110+
- **Consistent**: Predictable distribution schedule
111+
</TabItem>
112+
</Tabs>
113+
114+
---
115+
### Emission Accumulation Process
116+
117+
The accumulation mechanism efficiently processes emissions through a multi-stage pipeline:
118+
119+
1. **Interception**: When agents receive emissions, the system checks for active permissions
120+
2. **Stream Matching**: Permissions are filtered by stream ID and allocation type
121+
3. **Percentage Extraction**: For stream allocations, the specified percentage is extracted
122+
4. **Storage**: Accumulated amounts are stored with agent-stream-permission indexing
123+
5. **Distribution Triggers**: Various conditions trigger automatic distribution

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ The system supports three fundamental permission types that enable comprehensive
3636
```rust
3737
pub enum PermissionScope {
3838
Emission(EmissionScope), // Stream delegation permissions
39+
3940
Curator(CuratorScope), // Governance function delegation
4041
Capability(CapabilityScope), // Off-chain service access control
4142
}

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

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Create Emission Permission
3+
description: Step-by-step guide to creating emission 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 emission permissions** in the Torus portal.
17+
Emission permissions enable economic coordination by delegating portions of your token emission streams to other agents.
18+
19+
## Why Create Emission Permissions?
20+
21+
Emission 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 emission permissions](#create-emission-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 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.
46+
</Card>
47+
</CardGrid>
48+
49+
## Create Emission Permission
50+
51+
Emission permissions enable economic coordination by delegating portions of your token emission streams.
52+
53+
<Steps>
54+
55+
1. **Visit the [Create Permissions tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/emission)**
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 Emission tab**
62+
Select the <RedText variant="light">**Emission** tab instead of the **Capability** tab</RedText> to create emission 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+
# Threshold Amount
73+
Token amount threshold for automatic distribution
74+
(only shown for Automatic distribution type)
75+
76+
# Block Number
77+
Specific block number for one-time execution
78+
(only shown for At Block distribution type)
79+
80+
# Block Interval
81+
Number of blocks between periodic distributions
82+
(only shown for Interval distribution type)
83+
84+
# Duration Type
85+
- **Indefinite**: Permission remains valid indefinitely
86+
- **Until Block**: Permission expires at a specific block
87+
88+
# Revocation Type
89+
- **Irrevocable**: Cannot be revoked
90+
- **Revocable by Delegator**: Only the delegator can revoke
91+
- **Revocable by Arbiters**: Can be revoked by arbiters after
92+
a vote threshold set by the delegator
93+
- **After Block**: Can only be revoked after a specific block
94+
95+
# Streams
96+
Click **Add Stream** to add multiple emission streams:
97+
- **Stream ID**: Identifier of the emission stream to delegate
98+
- **Percentage**: Percentage of that stream to delegate (0-100%)
99+
100+
# Target Accounts
101+
Click **Add Target** to add multiple recipients:
102+
- **Account**: Wallet address of the recipient agent
103+
- **Weight**: Percentage weight for this recipient
104+
(distribution among multiple targets)
105+
```
106+
107+
5. **Review and Confirm**
108+
Double-check all details and click <RedText variant="light">**Create Permission**</RedText> to confirm.
109+
Sign the transaction in your Wallet to finish the creation.
110+
111+
6. **All Done**
112+
Your Emission Permission is now delegated. You can check it in the [Management tab](https://portal.torus.network/permissions/edit-permission).
113+
</Steps>
114+
115+
## What's Next?
116+
117+
After creating your emission permission, you can:
118+
119+
- **Monitor performance**: Track how recipients use delegated emissions
120+
- **Adjust permissions**: Modify terms based on agent performance
121+
- **Scale coordination**: Build complex multi-agent economic workflows
122+
- **Manage permissions**: View and revoke permissions through the [manage permissions guide](https://docs.torus.network/how-to-guides/system/manage-permissions/)
123+
124+
<Aside type="tip" title="Want to Learn More?">
125+
For more technical details about emission permissions, see the [emission permissions explanation](https://docs.torus.network/explanations/system/emission-permissions/).
126+
</Aside>

0 commit comments

Comments
 (0)