Skip to content
Torus Docs

Stream Permissions

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