Skip to content

Commit e832f6b

Browse files
SipherSipher
committed
Refactor documentation structure; rename sections, enhance clarity, and add new concepts for improved understanding of Torus workflow
1 parent 5ef5260 commit e832f6b

File tree

7 files changed

+185
-114
lines changed

7 files changed

+185
-114
lines changed

‎astro.config.mjs‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,9 @@ export default defineConfig({
2525
{
2626
label: "Getting Started",
2727
items: [
28-
{ label: "Introduction", slug: "index" },
28+
{ label: "Welcome", slug: "index" },
2929
{ label: "Tokenomics", slug: "getting-started/tokenomics" },
30-
{
31-
label: "Concepts & Terminology",
32-
slug: "getting-started/concepts",
33-
},
30+
{ label: "Understanding Torus", slug: "getting-started/concepts" },
3431
],
3532
},
3633
{

‎public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png‎

159 KB
Loading

‎src/content/docs/getting-started/concepts-terminology.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Concepts & Terminology
3+
description: Key terms and concepts used throughout the Torus ecosystem
4+
---
5+
6+
import { Aside } from "@astrojs/starlight/components";
7+
8+
9+
This glossary defines the key terms and concepts used throughout Torus documentation. Understanding these terms will help you navigate the ecosystem more effectively.
10+
11+
## Core Concepts
12+
13+
### Agent
14+
An autonomous entity in the Torus network that can perform actions, provide services, and participate in swarms. Agents can be registered users, automated services, or any entity capable of interacting with the protocol.
15+
16+
### Swarm
17+
A coordinated group of agents working together toward a common goal. Swarms form organically around specific objectives and can operate at multiple scales within the network.
18+
19+
### Hypergraph
20+
The emergent network structure formed by all agents, their relationships, permissions, and interactions. The hypergraph represents the complete state of coordination within Torus.
21+
22+
### Root Agent
23+
A special type of agent with elevated permissions to receive emissions directly from the protocol and set goals for swarm formation. Root agents lead major initiatives and coordinate large-scale activities.
24+
25+
## Permissions & Capabilities
26+
27+
### Capability
28+
A specific function or service that an agent can provide to others. Capabilities are registered on-chain and define what an agent can do within the network.
29+
30+
### Permission
31+
The right to use or delegate a specific capability. Permissions can be granted, revoked, and delegated between agents to enable complex coordination patterns.
32+
33+
### Delegation
34+
The process of granting permission to use a capability to another agent. Delegation enables specialization and collaborative work within swarms.
35+
36+
### Control Space
37+
The coordination layer where agents register capabilities, manage permissions, and coordinate activities. It serves as the control plane for the entire network.
38+
39+
## Economic Terms
40+
41+
### TORUS Token
42+
The native token of the Torus network used for staking, governance, and accessing network services.
43+
44+
### Staking
45+
The process of locking TORUS tokens to participate in network security and earn rewards. Staked tokens can be allocated to support specific agents.
46+
47+
### Emissions
48+
Token rewards distributed to agents and stakeholders based on their contributions to the network. Emissions flow from root agents to the broader ecosystem.
49+
50+
### Allocation
51+
The distribution of staked tokens to support specific agents or initiatives. Allocations determine how emissions flow through the network.
52+
53+
## Technical Terms
54+
55+
### Agent Server
56+
A service that hosts agent capabilities and provides APIs for other agents to interact with. Agent servers make capabilities discoverable and usable across the network.
57+
58+
### Agent Client
59+
A component that allows agents to discover and interact with capabilities provided by other agents. Clients handle authentication and communication protocols.
60+
61+
### Signal
62+
A message broadcast by an agent expressing demand for specific capabilities or announcing the availability of services. Signals help coordinate supply and demand within swarms.
63+
64+
### Substrate
65+
The blockchain framework that powers the Torus network. Substrate provides the runtime environment for the protocol's core functionality.
66+
67+
## Governance Terms
68+
69+
### DAO (Decentralized Autonomous Organization)
70+
The governance structure through which major protocol decisions are made. The Torus DAO enables stakeholder participation in network evolution.
71+
72+
### Proposal
73+
A formal suggestion for protocol changes, new features, or resource allocation submitted to the DAO for consideration and voting.
74+
75+
### Governance Token
76+
TORUS tokens used for voting on proposals and participating in decentralized governance processes.
77+
78+
<Aside>
79+
**New terms being added regularly.** As the Torus ecosystem evolves, new concepts and terminology emerge. Check back here for updates or suggest additions through our community channels.
80+
</Aside>

‎src/content/docs/getting-started/concepts.mdx‎

Lines changed: 11 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,23 @@
11
---
2-
title: High-level Concepts and Terminology
3-
description: In depth Torus concepts and terminology.
2+
title: Understanding Torus
3+
description: Layer1 self-assembling & self-optimizing autonomous super-swarm
44
---
55

6-
### Agent
6+
import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components";
77

8-
Registered key able to receive & delegate permissions over protocol & agent control space (on-chain / off-chain) and accumulate delegated incentive (coin emissions).
8+
# Layer1 self-assembling & self-optimizing autonomous super-swarm
99

10-
---
11-
### Protocol control space
12-
13-
A set of controls composed of all chain parameters and storages where corruption does not lead to loss of user holdings (e.g. weights, bonds).
14-
15-
---
16-
### Agent control space
17-
18-
Off-chain control space local to agents with any structure, any set of controls. The permission delegation system of agent control space is fully local with arbitrary design.
19-
20-
---
21-
### Controls
22-
23-
Atomic units of the control space
24-
25-
---
26-
### Permission
27-
28-
Programmatically defined authority over a set of controls that can be either exercised or delegated, either partially or fully, optionally with an added constraint - recursively.
29-
30-
permission-centric, there are 2 types of agents:
31-
32-
* controller
33-
34-
exercises the control authority of the permission, i.e. submitting extrinsics to the chain
35-
36-
* selector
37-
38-
dynamically delegates the permission to the best controlling agent
39-
40-
agents can take both the controller and selector role for different parts of their permission sets.
41-
42-
agent-centric, there are 2 types of permissions:
43-
44-
* direct permissions
45-
46-
require direct action to be delegated by an agent
47-
48-
* conditional permissions
49-
50-
require receiving agent to satisfy a condition set to automatically receive (and keep) the permission.
51-
52-
When a permission is adapted or revoked, the change propagates down the delegation tree. When an incentive delegation is adapted, it propagates proportionally down the tree.
53-
54-
---
55-
### Permission constraint
56-
57-
A programmatically defined constraint over the use of a permission, e.g. a limit on how often a permission can be re-delegated between agents or a set of conditions that have to be met by an agent to be re-delegated to, or a set of conditions that have to be met for the permission to be active. a condition could be state of offchain oracle.
58-
59-
---
60-
### Delegation
61-
62-
Transfer of permissions or incentive between agents with programmatic logic, the edges of the graph.
63-
64-
---
65-
### Circular Delegation
66-
67-
Circular delegation paths are allowed, but further re-delegation is blocked to avoid confusing paths. Higher level agents have permission to enforce irrevocable re-delegation to them, as an alternative to revoking a permission entirely such that the graph stays intact and can be immediately reverted back into.
68-
69-
This is the standard, but can be partially or fully constraint in the permission constraint defined by the higher level agent.
70-
71-
---
72-
### Stake root
73-
74-
Fully Stake-based permissionless control system and foundational authority and owner of the protocol control space, representing the root agent node of the Torus graph. Everything else is emergent from it through recursive delegation, and continuously aligns back to it. The most successful delegation tree over time should be the one most aligned and with the highest importance to the goals of stake.
10+
Torus is a stake-based p2p protocol for goal-driven agent swarm coordination. The system operates as one fractal super-swarm, which is composed of one emergent hypergraph of recursively delegated permissions and incentives among agents. Swarms are subgraphs, and can form at any position in the hypergraph.
7511

76-
The biological analogy for the stake root is the genome, where the genetic library is stored offchain in the evolving minds of the stakeholders and the Torus memeplex, continuously mutating, and the onchain stake-based control mechanism is the gene regulatory system, translating how the genetic library can express itself onto the Torus
12+
The Torus hypergraph emerges from and aligns back to the stake root, tethering the system to the interests of stake. Torus aligns towards the central point of stake, while stake is decentralized representing the system as a whole, effectively aligning it to itself.
7713

78-
---
79-
### Emissions
80-
81-
Emissions are the continuous distribution of TORUS tokens to agents based on their utility and stake allocation. The emission system operates through distinct streams that preserve their identity through delegation chains, enabling complete traceability of token flow from source to recipients.
82-
83-
Agents can delegate portions of their emissions to other agents through stream-based allocations (percentage-based) or fixed amount allocations, creating complex economic coordination structures. This enables recursive delegation where successful agents can redistribute incentives to supporting agents, aligning the entire network toward utility creation.
84-
85-
---
86-
### Namespace
87-
88-
A namespace is a hierarchical naming system that enables agents to organize and delegate access to their capabilities and services. Using dot-separated paths (like `agent.alice.memory.twitter`), namespaces create clear authority boundaries while enabling granular permission delegation for off-chain services.
14+
Swarms form bottom-up around top-down goals, their formation happens organically without central planning. Swarms operate as self-assembling multi-scale competency architectures, collectively navigating towards complex goals with full autonomy at every level and open competition at every edge.
8915

90-
Namespaces represent the *potential* for creating new controls, acting as genetic templates from which specific permissions can emerge. This distinction between namespace (potential) and control (actualized permission) enables the recursive delegation patterns that characterize complex agent coordination.
16+
The permission & delegation system enables agents to granularily specialize while remaining aligned across levels. Swarms collectively explore a problem space and engage in an open-ended process of recursive niche construction to navigate towards the swarms goal.
9117

92-
---
93-
### Torus graph
94-
95-
Dynamic multi-graph, where the edges are delegated permissions and incentives, representing the protocols emergent self-organization.
96-
97-
---
98-
### Graph event flow
99-
The central flow of chain events changing the structure of the protocol graph, which can be observed by anyone.
100-
101-
---
102-
### Organs
10318

104-
Organs are regions of the Torus graph, composed of emergent sets of agents that fulfill an emergent function of the Torus to increase its competency. E.g. memory, immune system, sense making, complexity pruning, propaganda. “Organ” is a useful term of an emergent construct, but not a primitive.
19+
#### v0.5
10520

106-
---
21+
The v0.5 is a pragmatic, growth oriented and limited implemention of the Torus conceptual model. It's mainnet release initiates the formation process of the Torus hypergraph and allows battletesting of our concepts. It is sufficient for the formation of sophisticated agent swarms and applies the core ideas.
10722

23+
The Torus v1 will be the pure and complete implementation of the Torus conceptual model and will be delivered after undergoing a growth phase with the v0.5.

‎src/content/docs/how-to-guides/builders/manage-capabilities.mdx‎

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
import ClickableImage from '/src/components/ClickableImage.astro';
1414
import RedText from '/src/components/RedText.astro';
1515
import confirmCapability from '/public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png';
16+
import deleteCapability from '/public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png';
1617

1718
In this guide, we'll walk through **managing capabilities** in the Torus control space.
1819
Capabilities allow you to integrate off-chain resources and services with Torus's on-chain permission system.
@@ -50,7 +51,7 @@ By removing outdated or unused capabilities, you reduce the attack surface and k
5051
<Steps>
5152

5253
1. **Visit the [Create Capability Tab in the Torus Portal](https://portal.torus.network/capabilities/create-capability)**
53-
Navigate to the **Capability Operations** section.
54+
Navigate to the **Capabilities** section in the Torus Portal.
5455

5556
2. **Connect your Torus Wallet**
5657
Ensure you're <RedText variant="light">connected with the agent account</RedText> that will own the capability.
@@ -106,4 +107,60 @@ By removing outdated or unused capabilities, you reduce the attack surface and k
106107

107108
## Delete a Capability path
108109

109-
WIP
110+
<Steps>
111+
112+
1. **Visit the [Delete Capability Tab in the Torus Portal](https://portal.torus.network/capabilities/delete-capability)**
113+
Navigate to the **Capabilities** section in the Portal.
114+
115+
2. **Connect your Torus Wallet**
116+
Ensure you're <RedText variant="light">connected with the agent account</RedText> that owns the capability you want to delete.
117+
118+
3. **Select the Capability Segment to Delete**
119+
From the dropdown menu, <RedText variant="light">choose the capability segment</RedText> you want to remove from your agent.
120+
121+
Capabilities are structured in segments like:
122+
**`agent.your-agent-name.test-path.get.depth.add.delete`**
123+
124+
<Aside type="note">
125+
**Understanding Segment-Based Deletion**
126+
127+
You can delete capabilities by segments, and <RedText variant="light">deletion always removes all subsequent segments</RedText>:
128+
129+
**Examples:**
130+
- Delete `.get` → Removes `.get.depth.add.delete`
131+
- Delete `.add` → Removes `.add.delete` (but keeps `.get.depth`)
132+
- Delete `.test-path` → Removes `.test-path.get.depth.add.delete`
133+
134+
In the **Delegation Preview**, <RedText variant="light">green segments will remain</RedText> and <RedText variant="light">red segments will be deleted</RedText>.
135+
</Aside>
136+
137+
<Aside type="caution">
138+
**Deleting a capability segment is permanent and cannot be undone.**
139+
140+
Once deleted, any permissions or integrations relying on the deleted segments will stop working immediately. Make sure you're certain about removing these capability segments before proceeding.
141+
</Aside>
142+
143+
4. **Review information, Submit and Sign the Transaction**
144+
<RedText variant="light">Review the capability path</RedText> you're about to delete in the preview field.
145+
If you're certain you want to proceed, click **Delete Capability**.
146+
Open the SubWallet extension and <RedText variant="light">sign the transaction</RedText>.
147+
<ClickableImage src={deleteCapability} alt="Confirm Capability" />
148+
149+
5. **All Done**
150+
You've successfully deleted the capability from the Torus control space.
151+
Any existing permissions or delegations to this capability are now invalid.
152+
153+
</Steps>
154+
155+
## What's Next?
156+
157+
Now that you can manage capabilities, you might want to:
158+
159+
- **Set up delegation**: Delegate permissions to allow other agents to use your capabilities *(coming soon)*
160+
- **Build agent services**: Create an [agent server](https://docs.torus.network/how-to-guides/builders/setup-agent-server/) to provide APIs that utilize your registered capabilities
161+
- **Create demand signals**: Signal for [specific capabilities](https://docs.torus.network/how-to-guides/builders/create-signal/) you need from other agents
162+
163+
Connect with the community:
164+
- [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements
165+
- [Telegram](https://t.me/torusnetwork) — General chat and announcements
166+
- [Twitter](https://x.com/torus_network) — Updates and ecosystem news

‎src/content/docs/how-to-guides/start-here.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ If you're developing tools, services, or integrations on Torus:
4040
- [Setup Agent Server](https://docs.torus.network/how-to-guides/builders/setup-agent-server/)
4141
- [Setup Agent Client](https://docs.torus.network/how-to-guides/builders/setup-agent-client/)
4242
- [Manage Capabilities](https://docs.torus.network/how-to-guides/builders/manage-capabilities/)
43-
- [Manage Permissions](https://docs.torus.network/how-to-guides/builders/manage-permissions/)
44-
- [Delegate Emission Streams](https://docs.torus.network/how-to-guides/builders/delegate-emission-streams/)
43+
- Manage Permissions _(coming soon)_
44+
- Delegate Emission Streams _(coming soon)_
4545

4646
---
4747

0 commit comments

Comments
 (0)