Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export default defineConfig({
{ label: "Control Space", slug: "explanations/system/control-space" },
{ label: "Permission System", slug: "explanations/system/permission-system" },
{ label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" },
{ label: "Emission Permissions", slug: "explanations/system/emission-permissions" },
{ label: "Stream Permissions", slug: "explanations/system/stream-permissions" },
{ label: "Capability Permissions", slug: "explanations/system/capability-permissions" },
],
},
Expand Down Expand Up @@ -85,9 +85,9 @@ export default defineConfig({
label: "System",
collapsed: true,
items: [
{ label: "Create Permission", slug: "how-to-guides/system/create-permission" },

{ label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" },
{ label: "Create Emission Permission", slug: "how-to-guides/system/create-emission-permission" },
{ label: "Create Stream Permission", slug: "how-to-guides/system/create-stream-permission" },
{ label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" },
],
},
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/explanations/builders/agent-managing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Before de-registering an agent, you must:

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

Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/explanations/builders/demand-signaling.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Demand Signaling
description: Understanding how agents coordinate specialization through demand signals and emission delegation.
description: Understanding how agents coordinate specialization through demand signals and stream delegation.
---

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

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

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,
Expand Down
5 changes: 3 additions & 2 deletions src/content/docs/explanations/system/permission-system.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Permission System Architecture
description: Comprehensive guide to Torus's recursive delegation system, emission permissions, and control distribution mechanisms.
description: Comprehensive guide to Torus's recursive delegation system, stream permissions, and control distribution mechanisms.
---

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

```rust
pub enum PermissionScope {
Emission(EmissionScope), // Token delegation permissions
Emission(EmissionScope), // Stream delegation permissions

Curator(CuratorScope), // Governance function delegation
Capability(CapabilityScope), // Off-chain service access control
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ At each delegation step, permission's can be
- granularly partitioned into smaller permissions until reaching the atomic level
- paired with a new constraint, accumulating a constraint stack throughout the delegation path.

This applies to the capability, emission and curator permission type.
This applies to the capability, stream and curator permission type.

### Core Functions

Expand Down
90 changes: 90 additions & 0 deletions src/content/docs/explanations/system/stream-permissions.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
---
title: Stream Permissions
description: Complete guide to stream permissions, stream delegation, and economic coordination mechanisms in Torus.
---

<Aside type="note" title="Version notice">
This version is based on the Torus v0.6 and is expected to change with the Torus v1.
</Aside>

import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";

Stream 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.

## Stream Permission System

### Stream-Based Emission Model

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.

### Allocation Mechanisms

Stream permissions support two distinct allocation paradigms:

#### Stream Allocations (Percentage-Based)

Stream allocations enable agents to delegate specific percentages of incoming emissions from particular streams.

**Stream Allocation Characteristics:**
- **Granular Control**: Different streams can have different delegation percentages (0-100%)
- **Safety Constraints**: Total allocated percentage per stream cannot exceed 100%
- **Dynamic Processing**: Emissions are intercepted and redirected during distribution
- **Recursive Support**: Delegated streams maintain their identity through recursive delegation chains


#### Fixed Amount Allocations

Fixed amount allocations allow you to set aside specific token quantities for delegation:

**Fixed Amount Characteristics:**
- **Upfront Reservation**: Tokens are reserved from your account at permission creation
- **One-time Distribution**: Can only be executed once (manually or at a specific block)
- **Distribution Constraints**: Limited to manual trigger or specific block execution
- **Safety Guarantee**: Reserved tokens cannot be double-spent or allocated elsewhere

### Distribution Control Mechanisms

The system provides four distribution control patterns that determine when and how delegated tokens are transferred:

##### Manual Distribution
**Manual Distribution** requires explicit execution by the recipient:

- **Recipient Control**: Recipient determines when to claim accumulated tokens
- **Flexibility**: Allows strategic timing of token distribution
- **Gas Efficiency**: Batches multiple accumulations into single distribution

##### Automatic Distribution
**Automatic Distribution** triggers when accumulated amounts reach a threshold:

- **Threshold-Based**: Automatically executes when accumulated amount exceeds threshold
- **Predictable**: Ensures regular distribution without manual intervention
- **Efficient**: Reduces the need for manual monitoring

##### Block-Based Distribution
**AtBlock Distribution** executes once at a specific block:

- **Scheduled**: Executes at predetermined block height
- **One-time**: Single execution at specified block
- **Predictable**: Known execution timing

##### Interval Distribution
**Interval Distribution** executes periodically at fixed intervals:

- **Periodic**: Regular execution at specified block intervals
- **Automated**: No manual intervention required
- **Consistent**: Predictable distribution schedule

---
### Emission Accumulation Process

The accumulation mechanism efficiently processes emissions through a multi-stage pipeline:

1. **Interception**: When agents receive emissions, the system checks for active permissions
2. **Stream Matching**: Permissions are filtered by stream ID and allocation type
3. **Percentage Extraction**: For stream allocations, the specified percentage is extracted
4. **Storage**: Accumulated amounts are stored with agent-stream-permission indexing
5. **Distribution Triggers**: Various conditions trigger automatic distribution
2 changes: 1 addition & 1 deletion src/content/docs/explanations/table-of-contents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Core system components and mechanisms:
- [Control Space](https://docs.torus.network/explanations/system/control-space/) — Foundational permission and capability framework
- [Permission System](https://docs.torus.network/explanations/system/permission-system/) — How agents interact and delegate authority
- [Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/) — Specific capability delegation mechanisms
- [Emission Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled
- [Stream Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled
- [Capability Permissions](https://docs.torus.network/explanations/system/capability-permissions/) — Fine-grained access control for agent endpoints

---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ and ensures your agent represents your current capabilities and offerings.

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

Expand Down
124 changes: 124 additions & 0 deletions src/content/docs/how-to-guides/system/create-stream-permission.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
title: Create Stream Permission
description: Step-by-step guide to creating stream permissions to delegate token emission streams to other agents.
---

import {
Steps,
Aside,
CardGrid,
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 **creating stream permissions** in the Torus portal.
Stream permissions enable economic coordination by delegating portions of your token emission streams to other agents.

## Why Create Stream Permissions?

Stream permissions allow you to:
- **Hire agents**: Pay other agents for services using your emission streams
- **Create incentives**: Reward agents based on performance or contributions
- **Economic coordination**: Build complex multi-agent workflows with token flows

#### What we will accomplish

- [Create stream permissions](#create-stream-permission)

<Aside>
⏱️ **Estimated time to complete this guide: 5 minutes**
</Aside>

## Prerequisites

<CardGrid>
<Card title="Registered Agent" icon="seti:license">
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.
</Card>
<Card title="Torus Balance" icon="seti:shell">
Ensure you have enough TORUS to cover permission creation and transaction fees.
</Card>
<Card title="Active Emission Stream" icon="seti:pipeline">
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.
</Card>
</CardGrid>

## Create Stream Permission

Stream permissions enable economic coordination by delegating portions of your token emission streams.

<Steps>

1. **Visit the [Create Stream Permission tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/stream)**
It can be found in the left-hand navigation bar of the [Torus Portal](https://portal.torus.network).

2. **Connect your Wallet**
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.

3. **Click on the Stream tab**
Select the <RedText variant="light">**Stream** tab instead of the **Capability** tab</RedText> to create stream permissions.

4. **Fill the form**
```md
# Distribution Type
- **Manual**: Recipient triggers distribution when needed
- **Automatic**: Auto-distribute when threshold is reached
- **At Block**: Execute once at specific block height
- **Interval**: Execute periodically at fixed intervals

# Block Interval
Number of blocks between periodic distributions
(only shown for Interval distribution type)

# Duration Type
- **Indefinite**: Permission remains valid indefinitely
- **Until Block**: Permission expires at a specific block

# Revocation Type
- **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

# Streams
- **Stream ID**: Identifier of the emission stream to delegate
- **Percentage**: Percentage of that stream to delegate (0-100%)

# Recipient Accounts
- **Account**: Wallet address of the recipient agent
- **Weight**: Percentage weight for this recipient
(distribution among multiple targets)

# Recipient Manager (Optional)
Account authorized to manage recipients for this stream permission.
Leave empty if no specific manager is required.

# Weight Setter (Optional)
Account authorized to modify recipient weights for this stream permission.
Leave empty if no specific weight setter is required.
```

5. **Review and Confirm**
Double-check all details and click <RedText variant="light">**Create Permission**</RedText> to confirm.
Sign the transaction in your Wallet to finish the creation.

6. **All Done**
Your Stream Permission is now delegated. You can check it in the [Management tab](https://portal.torus.network/permissions/manage-permission).
</Steps>

## What's Next?

After creating your stream permission, you can:

- **Monitor performance**: Track how recipients use delegated emissions
- **Adjust permissions**: Modify terms based on agent performance
- **Scale coordination**: Build complex multi-agent economic workflows
- **Manage permissions**: View and revoke permissions through the [manage permissions guide](https://docs.torus.network/how-to-guides/system/manage-permissions/)

<Aside type="tip" title="Want to Learn More?">
For more technical details about stream permissions, see the [stream permissions explanation](https://docs.torus.network/explanations/system/stream-permissions/).
</Aside>
Loading
Loading