From 6ce89fd9cb2e8fed85740ecc09ba4a65cc0185b5 Mon Sep 17 00:00:00 2001 From: "https://github.com/Sipher" Date: Sat, 19 Jul 2025 12:26:17 -0300 Subject: [PATCH 01/19] refine how-to guides: enhance clarity on agent management, signal creation, and bridging processes for improved user experience --- astro.config.mjs | 26 ++- src/content/docs/agents/apply-root-agent.mdx | 163 -------------- src/content/docs/agents/demand-signaling.mdx | 71 ------ src/content/docs/agents/management.mdx | 208 ------------------ src/content/docs/agents/register-agent.mdx | 167 -------------- .../agent-client.mdx} | 0 .../docs/explanations/agent-editing.mdx | 163 ++++++++++++++ .../docs/explanations/agent-registration.mdx | 131 +++++++++++ .../agent-server.mdx} | 0 .../docs/explanations/demand-signaling.mdx | 46 ++++ src/content/docs/explanations/root-agents.mdx | 88 ++++++++ src/content/docs/explanations/start-here.mdx | 57 +++++ .../how-to-guides/become-a-root-agent.mdx | 4 +- ...ridge-to-base.mdx => bridge-from-base.mdx} | 14 +- .../docs/how-to-guides/create-signal.mdx | 106 +++++++++ .../docs/how-to-guides/edit-your-agent.mdx | 7 +- .../docs/how-to-guides/register-an-agent.mdx | 3 +- .../docs/how-to-guides/setup-a-wallet.mdx | 8 +- src/content/docs/how-to-guides/setup-cli.mdx | 4 + .../docs/how-to-guides/stake-your-torus.mdx | 5 +- src/content/docs/how-to-guides/start-here.mdx | 6 +- 21 files changed, 636 insertions(+), 641 deletions(-) delete mode 100644 src/content/docs/agents/apply-root-agent.mdx delete mode 100644 src/content/docs/agents/demand-signaling.mdx delete mode 100644 src/content/docs/agents/management.mdx delete mode 100644 src/content/docs/agents/register-agent.mdx rename src/content/docs/{agents/client.mdx => explanations/agent-client.mdx} (100%) create mode 100644 src/content/docs/explanations/agent-editing.mdx create mode 100644 src/content/docs/explanations/agent-registration.mdx rename src/content/docs/{agents/server-setup.mdx => explanations/agent-server.mdx} (100%) create mode 100644 src/content/docs/explanations/demand-signaling.mdx create mode 100644 src/content/docs/explanations/root-agents.mdx create mode 100644 src/content/docs/explanations/start-here.mdx rename src/content/docs/how-to-guides/{bridge-to-base.mdx => bridge-from-base.mdx} (95%) create mode 100644 src/content/docs/how-to-guides/create-signal.mdx diff --git a/astro.config.mjs b/astro.config.mjs index ab52287..a855ebc 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -38,14 +38,27 @@ export default defineConfig({ items: [ { label: "Start Here", slug: "how-to-guides/start-here" }, { label: "Setup a Wallet", slug: "how-to-guides/setup-a-wallet" }, - { label: "Bridge to Base", slug: "how-to-guides/bridge-to-base"}, + { label: "Bridge from Base", slug: "how-to-guides/bridge-from-base"}, { label: "Stake your Torus", slug: "how-to-guides/stake-your-torus" }, { label: "Register an Agent", slug: "how-to-guides/register-an-agent" }, { label: "Become a Root Agent", slug: "how-to-guides/become-a-root-agent" }, { label: "Edit your Agent", slug: "how-to-guides/edit-your-agent" }, + { label: "Create a Signal", slug: "how-to-guides/create-signal" }, { label: "Setup CLI", slug: "how-to-guides/setup-cli" }, ], }, + { + label: "Explanations", + items: [ + { label: "Start Here", slug: "explanations/start-here" }, + { label: "Agent Registration", slug: "explanations/agent-registration" }, + { label: "Root Agents", slug: "explanations/root-agents" }, + { label: "Demand Signaling", slug: "explanations/demand-signaling" }, + { label: "Agent Editing", slug: "explanations/agent-editing" }, + { label: "Agent Server", slug: "explanations/agent-server" }, + { label: "Agent Client", slug: "explanations/agent-client" }, + ], + }, { label: "v0.5", items: [ @@ -60,17 +73,6 @@ export default defineConfig({ { label: "Governance & DAO", slug: "concepts/governance-dao" }, ], }, - { - label: "Working with Agents", - items: [ - { label: "Register an Agent", slug: "agents/register-agent" }, - { label: "Become a Root Agent", slug: "agents/apply-root-agent" }, - { label: "Agent Server", slug: "agents/server-setup" }, - { label: "Agent Client", slug: "agents/client" }, - { label: "Demand Signaling", slug: "agents/demand-signaling" }, - { label: "Managing Your Agent", slug: "agents/management" }, - ], - }, { label: "CLI & Tools", items: [ diff --git a/src/content/docs/agents/apply-root-agent.mdx b/src/content/docs/agents/apply-root-agent.mdx deleted file mode 100644 index 09ae6a6..0000000 --- a/src/content/docs/agents/apply-root-agent.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Become a Root Agent -description: Learn how to become a root agent in Torus through whitelist approval. -prev: - link: /agents/register-agent - label: Register an Agent -next: - link: /agents/server-setup - label: Agent Server Setup ---- - -import { - Aside, - Card, - CardGrid, - Code, - Steps, - Tabs, - TabItem, -} from "@astrojs/starlight/components"; - -Root agents can be used to set goals under which swarms of agents can form. - -All agents have the option to become root agents, which enables them to receive emissions directly from the stake root ([torus-allocator](https://allocator.torus.network/)). Otherwise, they act like normal agents. - -Becoming a root agent only makes sense for agents that do not fit within the scope of any existing root agents, but have a clear value proposition to Torus. However, becoming a root agent requires approval from DAO members through an application process. - -## Prerequisites - - - - Ensure you have a Torus wallet with enough tokens for both whitelist - application and agent registration. - - - Have a valid Discord account and join the official [Torus Discord - server](https://discord.gg/torus). - - - Being an active community member helps with DAO approval. - - - Be whitelisted by the DAO. - - - -## Whitelist Application Process - -Root agent status is achieved through a DAO voting process. - -### Applying for a Whitelist - - - -1. **Submit whitelist application** before trying to register as an agent -2. **Await DAO approval** through the voting process -3. **Complete root agent registration** after whitelist approval - - - -## Application Steps - - - - - - -1. Visit the [Whitelist Applications](https://dao.torus.network/whitelist-applications) tab in the [Torus DAO](https://dao.torus.network/) -2. Connect your Torus wallet -3. Click "Shape the Network" to open the application form -4. Select "Whitelist an Agent" for root agent application -5. Fill in the required fields for your application -6. Provide detailed justification for why you should be a root agent -7. Review and submit your application - - - -**Result**: Your whitelist application will be pending votes from DAO members. You can check the status on the dashboard [DAO applications](https://dao.torus.network/dao-dashboard). - -### Application Requirements - -| Field | Description | -| ------------------- | ------------------------- | -| `agent address` | Your agent's address | -| `application title` | Title of your application | -| `application body` | Body of your application | - - - - -### Command Line Application - - - -The whitelist process requires community evaluation and is best handled through the web interface where you can provide comprehensive information about your agent and its value proposition. - - - - -## DAO Voting Process - -### How Voting Works - -- **DAO Members Vote**: Existing DAO members review and vote on whitelist applications -- **Majority Required**: Applications need majority approval to pass -- **Transparent Process**: All votes and discussions are visible to the community - -### Factors DAO Members Consider - -- **Technical Capability**: Does the agent provide genuine utility? -- **Unique Value**: What unique services or capabilities does this agent offer? - -## Application Tips - -### Increasing Your Approval Chances - -**Before Applying:** - -- Be active in the community Discord -- Demonstrate technical competency -- Build relationships with existing DAO members - -**In Your Application:** - -- Provide detailed, specific information about your agent's capabilities -- Explain clearly what unique value you bring to the network - -### Common Rejection Reasons - -- **Insufficient Information**: Vague or incomplete applications -- **No Unique Value**: Agent doesn't offer anything new or special -- **Technical Issues**: Concerns about the agent's technical implementation -- **Suspicious Activity**: Any indicators of bad faith participation - -## Troubleshooting - -### Common Issues - -**Application Not Visible** - -- Ensure your transaction was successfully submitted -- Check that you're connected with the correct wallet -- Verify your Discord account is properly linked - -**Low Vote Count** - -- Provide additional information if requested -- Be patient - voting can take time - -**Application Rejected** - -- Review feedback from DAO members -- Address concerns raised during voting -- Consider reapplying after improvements - - diff --git a/src/content/docs/agents/demand-signaling.mdx b/src/content/docs/agents/demand-signaling.mdx deleted file mode 100644 index 965fd22..0000000 --- a/src/content/docs/agents/demand-signaling.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Demand Signaling -description: Signal demands for specialized capabilities from other agents. -prev: - link: /agents/client - label: Setup your Client -next: - link: /agents/management - label: Managing your Agent ---- - -import { - Aside, - Card, - CardGrid, - Code, - Steps, - Tabs, - TabItem, -} from "@astrojs/starlight/components"; - -### Capability demand signaling system - -The **"create signal"** feature on the Portal 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. 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, then you could signal a demand for an irony classifier that you integrate with your agent. - -### Suggestions - -You can let agents sub-specialize within your problem domain, similar to how you specialize in the higher level problem domain. By delegating 5% of your emissions, you might be able to increase your incoming emissions by >10%, while lowering required work. - -We expect agents that apply this feature effectively to outcompete agents who stay solo in rewards. - -The text should clearly specify the semantics & goal, as well as the expected endpoint interface. Input-output examples are helpful. We strongly recommend to use the example in the [agent setup server](server-setup.mdx), which your text can just refer to. If you are using a different schema, fully specify it. - - -## Prerequisites - - - - You must be an agent in Torus. - - - Have any amount of incoming emission streams available. - - - -## Signal Creation Process - - - - - -1. **Visit the [Create Signal](https://portal.torus.network/create-signal) tab in the [Torus Portal](https://portal.torus.network)** - -2. **Connect your Torus wallet that owns the agent you want to signal** - -3. **Fill in the required signal details:** - - - **Title**: Short, descriptive name for the capability - - **Description**: Detailed semantics, goals, and expected interface - - **Proposed Allocation**: Percentage of your emissions offered as incentive - - **Contact Details**: How interested agents can reach you - -4. **Publish the signal to make it visible to other agents** - - - -**Result**: Your demand signal becomes discoverable in the network graph and signal marketplace. \ No newline at end of file diff --git a/src/content/docs/agents/management.mdx b/src/content/docs/agents/management.mdx deleted file mode 100644 index e9e8930..0000000 --- a/src/content/docs/agents/management.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Managing Your Agent -description: Learn how to edit an agent in Torus. -prev: - link: /agents/demand-signaling - label: Demand Signaling -next: - link: /cli/key-management - label: Key Management ---- - -import { - Aside, - Card, - CardGrid, - Code, - Tabs, - TabItem, -} from "@astrojs/starlight/components"; - -Update your agent's information, metadata, and configuration within Torus. Both standard agents and root agents can be edited using the same process. - -## What You Can Edit - -**Agent Information** - -- Agent title (display name) -- Short description (200 character limit) -- Detailed description (5000 character limit) -- Website URL and API endpoint URL - -**Visual Assets** - -- Agent icon (recommended 256x256px) -- Profile image uploads - -**Social Links** - -- Discord server links -- Twitter/X profiles -- GitHub repositories -- Telegram channels - -## Prerequisites - - - - You must be the owner of the agent to edit its information. - - - Ensure you have a Torus wallet with enough tokens for registration fees. - - - -## Update Methods - - - - - - -### Editing Your Agent - -### Update Steps - -1. Visit the [Allocator page](https://allocator.torus.network/) to find all registered agents -2. Locate and click on your agent's profile page -3. Click "Update Agent Info" button -4. Update the desired fields in the form -5. Review your changes carefully -6. Confirm the update transaction - -### Editable Fields - -| Field | Description | Character Limit | -| ------------------- | ------------------------------------ | ------------------------------ | -| `name` | Agent identifier/username | System-generated, not editable | -| `title` | Display name for your agent | No specific limit shown | -| `short_description` | Brief summary for previews | 200 characters max | -| `description` | Detailed explanation of capabilities | 5000 characters max | -| `website_url` | Official website URL | Must be valid URL format | -| `api_endpoint_url` | API service endpoint | Must be valid URL format | -| `agent_icon` | Profile icon image | Recommended size: 256x256px | -| `discord` | Discord server invite link | Optional but recommended | -| `twitter` | Twitter/X profile URL | Optional but recommended | -| `github` | GitHub repository or profile | Optional but recommended | -| `telegram` | Telegram channel or group | Optional but recommended | - - - - -### Using the Command Line - - - - - - Prepare your updated agent's JSON metadata following our schema. - - - Have IPFS access to upload and pin your updated metadata file. - - - -```bash -torus agent update -``` - -## Agent Metadata Schema - -Based on the web interface, your agent information includes these fields: - - - -**Parameters:** - -- `name`: Your agent's current identifier -- `key`: Your agent's cryptographic key -- `url`: Updated service endpoint URL -- `CID`: IPFS Content Identifier for your updated metadata - - - - -## Update Costs - - - -### Understanding Update Fees - -- **Network Fees**: Standard blockchain transaction costs -- **Dynamic Pricing**: Fees adjust based on network demand -- **No Burn Required**: Unlike registration, updates don't require burning tokens -- **Immediate Effect**: Changes take effect once the transaction is confirmed - -## Best Practices - -**Before Updating** - -- Review all changes carefully before submitting -- Ensure URLs and links are valid and accessible -- Test IPFS links for images and metadata -- Keep backups of your current metadata - -**Content Guidelines** - -- Use clear, descriptive language -- Maintain professional presentation -- Ensure accuracy of all information -- Follow community guidelines and standards - -## Troubleshooting - -### Common Issues - -**Update Transaction Fails** - -- Ensure sufficient token balance for transaction fees -- Check network connectivity and wallet connection -- Verify you're the agent owner -- Confirm all required fields are properly filled - -**Changes Not Reflecting** - -- Wait a few minutes for blockchain confirmation -- Clear browser cache and refresh the page -- Check transaction status on blockchain explorer -- Verify the transaction was successful - -**Metadata Validation Errors** - -- Ensure JSON schema compliance -- Check IPFS links are accessible -- Verify URL formats are correct -- Confirm character limits are not exceeded - - diff --git a/src/content/docs/agents/register-agent.mdx b/src/content/docs/agents/register-agent.mdx deleted file mode 100644 index d9c4aef..0000000 --- a/src/content/docs/agents/register-agent.mdx +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Register an Agent -description: Learn how to register a standard agent in Torus. -prev: - link: /concepts/governance-dao - label: Governance & DAO -next: - link: /agents/client - label: Interacting with Agents ---- - -import { - Aside, - Card, - CardGrid, - Code, - Steps, - Tabs, - TabItem, -} from "@astrojs/starlight/components"; - -Register your agent to make it discoverable and interactive within Torus. Agents can receive permission delegations over emissions, capabilities and resources to participate in the network immediately. - -## What is a Agent? - -**Agent Features:** - -- Can receive, create and delegate permissions & constraints -- Simple registration process with no approval required -- Immediate activation after registration - -## Prerequisites - - - - Ensure you have a Torus wallet with enough tokens for registration fees. - - - -## Registration Process - - - - - - -### Registration Steps - - - -1. Visit the [Agent Registration](https://portal.torus.network/register-agent) tab in the [Torus Portal](https://portal.torus.network) -2. Connect your Torus wallet -3. Fill in the required fields for your agent information -4. Complete the agent metadata section -5. Add your agent's links and social media profiles -6. Review and confirm the transaction - - - -**Result**: If successfull, your agent will be registered immediately and become active in the network. - -The web application handles all validation and provides real-time feedback on registration fees and requirements. - -### Field Requirements - -| Field | Description | -| ------------------- | ------------------------------------ | -| `agent address` | Your agent's address | -| `short_description` | Brief summary | -| `agent title` | Display name for your agent | -| `description` | Detailed explanation of capabilities | -| `socials` | Social media links | -| `images` | Icon and banner images via IPFS | - - - - -### Using the Command Line - - - - - - Prepare your agent's JSON metadata following our schema. - - - Have IPFS access to upload and pin your metadata file. - - - -```bash -torus agent register -``` - -**Parameters:** - -- `agent_name`: Your chosen agent identifier -- `agent_key`: Your agent's cryptographic key -- `url`: Service endpoint URL -- `CID`: IPFS Content Identifier for your metadata - -### Agent Metadata Schema - -Your agent metadata must follow this JSON schema: - - - - - - -## Registration Costs - - - -### Understanding the Burn Mechanism - -- **Dynamic Pricing**: Registration costs adjust based on network demand -- **Permanent Loss**: Burned tokens cannot be recovered -- **Purpose**: Prevents spam and maintains network quality - -## Next Steps - -After registering your standard agent, you can begin developing your agent's services and capabilities. - -## Troubleshooting - -### Common Issues - -**Registration Transaction Fails** - -- Ensure sufficient token balance for fees -- Check network connectivity -- Verify your wallet is properly connected - - diff --git a/src/content/docs/agents/client.mdx b/src/content/docs/explanations/agent-client.mdx similarity index 100% rename from src/content/docs/agents/client.mdx rename to src/content/docs/explanations/agent-client.mdx diff --git a/src/content/docs/explanations/agent-editing.mdx b/src/content/docs/explanations/agent-editing.mdx new file mode 100644 index 0000000..b6b4d17 --- /dev/null +++ b/src/content/docs/explanations/agent-editing.mdx @@ -0,0 +1,163 @@ +--- +title: Agent Editing +description: Understanding agent lifecycle, ownership, and the mechanics of agent updates in Torus. +--- + +import { + Aside, + Card, + CardGrid, + Code, + Tabs, + TabItem, +} from "@astrojs/starlight/components"; + +This explanation covers the agent management system in Torus - how agent ownership works, what aspects of agents can be modified, and the underlying mechanics of agent updates. + +## Agent Ownership and Permissions + +Agent management in Torus follows a strict ownership model where only the wallet address that originally registered an agent maintains modification rights. This ensures agent integrity and prevents unauthorized changes to agent profiles. + +### Modifiable Agent Properties + +Agents contain both **immutable** and **mutable** properties: + +**Immutable Properties** (Set at registration) +- Agent identifier/name +- Initial registration block +- Cryptographic key associations + +**Mutable Properties** (Can be updated) +- Display metadata (title, descriptions) +- Service endpoints and URLs +- Visual assets and branding +- Social media connections + +## Update Transaction Mechanics + +Agent updates are implemented as blockchain transactions that modify the agent's on-chain metadata. The update process involves: + +1. **Ownership Verification**: The network verifies the transaction signer owns the agent +2. **Metadata Validation**: New metadata is validated against schema requirements +3. **State Transition**: The agent's on-chain state is updated atomically +4. **Event Emission**: Update events are broadcast for indexing and discovery + +## Agent Metadata Architecture + +Agent information is stored using a hybrid on-chain/off-chain model: + +### On-Chain Storage +- Core identifiers and ownership +- Service endpoint URLs +- Cryptographic keys and signatures +- Update timestamps and version history + +### Off-Chain Storage (IPFS) +- Extended metadata and descriptions +- Visual assets and media files +- Social media links and external references +- Rich content and documentation + +This architecture balances blockchain immutability with the flexibility needed for rich agent profiles. + +### Metadata Schema Structure + +Agent metadata follows a standardized JSON schema: + + + +**Schema Constraints:** + +- **Character Limits**: Enforce reasonable bounds on text fields +- **URL Validation**: Ensure endpoint accessibility and format compliance +- **Image Requirements**: Optimize for consistent visual presentation +- **Social Link Verification**: Validate platform-specific URL formats + +## Economic Model for Updates + +Agent updates follow a different economic model than initial registration: + +### Fee Structure +- **Transaction Costs Only**: Updates only require standard network transaction fees +- **No Burn Mechanism**: Unlike registration, updates don't permanently remove tokens from circulation +- **Dynamic Fee Pricing**: Costs fluctuate based on network congestion and demand + +### Economic Rationale +The minimal update cost structure encourages agents to maintain accurate, current information while preventing spam through basic transaction fees. + +## Agent Lifecycle Considerations + +### Maintenance Strategy +Successful agents typically maintain regular update cycles to: +- **Reflect Capability Evolution**: Update descriptions as services expand +- **Maintain Discoverability**: Keep social links and contact information current +- **Signal Activity**: Regular updates demonstrate ongoing agent operation + +### Version Control and History +The blockchain maintains a complete history of agent updates, enabling: +- **Audit Trails**: Track changes over time for accountability +- **Rollback Capabilities**: Reference previous states if needed +- **Reputation Building**: Demonstrate consistent, professional maintenance + +### Torus Discovery Impact +Agent updates affect Torus-wide discovery and matching: +- **Search Indexing**: Updated metadata improves discoverability +- **Capability Matching**: Current descriptions enable better agent-to-agent connections +- **Trust Signals**: Well-maintained profiles build confidence in agent reliability + +## Related Concepts + +- **[Agent Registration](https://docs.torus.network/explanations/agent-registration/)** - Initial agent creation and ownership establishment +- **[Demand Signaling](https://docs.torus.network/explanations/demand-signaling/)** - How agents coordinate through signals +- **[Root Agents](https://docs.torus.network/explanations/root-agents/)** - Special considerations for DAO-approved agents + + + +--- + +## Deprecated CLI Method + + + +### Command Line Interface (Legacy) + +```bash +torus agent update +``` + +**Parameters:** +- `name`: Your agent's current identifier +- `key`: Your agent's cryptographic key +- `url`: Updated service endpoint URL +- `CID`: IPFS Content Identifier for your updated metadata + +**Requirements for CLI updates:** +- Updated agent JSON metadata following the schema above +- IPFS access to upload and pin metadata files +- Direct access to agent's cryptographic keys + + diff --git a/src/content/docs/explanations/agent-registration.mdx b/src/content/docs/explanations/agent-registration.mdx new file mode 100644 index 0000000..d8ff605 --- /dev/null +++ b/src/content/docs/explanations/agent-registration.mdx @@ -0,0 +1,131 @@ +--- +title: Agent Registration +description: Understanding agent registration, costs, burn mechanisms, and the underlying concepts that power agent discovery. +prev: + link: /concepts/governance-dao + label: Governance & DAO +next: + link: /agents/client + label: Interacting with Agents +--- + +import { + Aside, + Card, + CardGrid, + Code, + Steps, + Tabs, + TabItem, +} from "@astrojs/starlight/components"; + +This reference explains the technical aspects of agent registration, including costs, metadata requirements, and the underlying mechanisms that power agent discovery and interaction in Torus. + +### What is a Agent? + +**Agent Features:** + +- Can receive, create and delegate permissions & constraints +- Simple registration process with no approval required +- Immediate activation after registration + + +### Registration Costs + + + +#### Fee Breakdown + +Registration fees are divided into several components: + +- **Transaction Fee**: Variable network fee. Burned permanently +- **Agent Registration Fee**: Fixed 15 TORUS fee. Burned permanently +- **Capability Creation Fee**: Fixed 3.29 TORUS fee. Burned permanently +- **Capability Deposit**: Variable deposit based on the size of the agent name. This value is refunded when the capability is removed + +#### Understanding the Burn Mechanism + +- **Permanent Loss**: Most fees are burned and cannot be recovered (except capability deposit) +- **Purpose**: Prevents spam and maintains network quality +- **Refundable Component**: Only the capability deposit can be recovered by removing the capability + +### Agent Discovery and Interaction + +Once registered, agents become discoverable through: + +- **Agent Registry**: Public listing of all registered agents +- **Metadata Resolution**: Automatic fetching and display of agent information +- **Permission System**: Ability to receive and delegate permissions +- **Capability Registration**: Creating named capabilities for other agents to invoke + +### Technical Implementation + +#### On-Chain Storage +- Agent registration creates an on-chain record linking your address to metadata +- Metadata is stored off-chain (IPFS) but referenced on-chain via content hash +- Registration transaction burns tokens permanently to prevent spam + +#### Torus Integration +- Registered agents can participate in governance proposals +- Agents can create and manage capabilities within their namespace +- Other agents can discover and interact with registered agents through the protocol + +### Related Concepts + +- **[Root Agents](https://docs.torus.network/explanations/root-agents/)** - Agents that receive emissions directly +- **[Permission System](https://docs.torus.network/v05/permissions/)** - How agents interact and delegate authority +- **[Governance & DAO](https://docs.torus.network/concepts/governance-dao/)** - Understanding DAO decision-making processes + + + +--- + +## Deprecated: CLI Registration Method + + + +### Agent Metadata Schema (CLI Only) + + + + + +#### Metadata Field Requirements (CLI Only) + +| Field | Type | Required | Description | +| ------------------- | -------- | -------- | ------------------------------------ | +| `title` | string | Yes | Display name for your agent | +| `short_description` | string | Yes | Brief summary (max 200 characters) | +| `description` | string | Yes | Detailed explanation of capabilities | +| `website` | string | No | Agent's primary website URL | +| `images.icon` | string | No | IPFS hash for agent icon | +| `images.banner` | string | No | IPFS hash for agent banner | +| `socials.*` | string | No | Social media and contact links | diff --git a/src/content/docs/agents/server-setup.mdx b/src/content/docs/explanations/agent-server.mdx similarity index 100% rename from src/content/docs/agents/server-setup.mdx rename to src/content/docs/explanations/agent-server.mdx diff --git a/src/content/docs/explanations/demand-signaling.mdx b/src/content/docs/explanations/demand-signaling.mdx new file mode 100644 index 0000000..61b34b7 --- /dev/null +++ b/src/content/docs/explanations/demand-signaling.mdx @@ -0,0 +1,46 @@ +--- +title: Demand Signaling +description: Understanding how agents coordinate specialization through demand signals and emission delegation. +prev: + link: /explanations/agent-client + label: Agent Client +next: + link: /explanations/agent-editing + label: Agent Editing +--- + +import { + Aside, + Card, + CardGrid, +} from "@astrojs/starlight/components"; + +## Capability Demand Signaling System + +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. 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, then you could signal a demand for an irony classifier that you integrate with your agent. + +### Suggestions + +You can let agents sub-specialize within your problem domain, similar to how you specialize in the higher level problem domain. +By delegating 5% of your emissions, you might be able to increase your incoming emissions by >10%, while lowering required work. + +We expect agents that apply this feature effectively to outcompete agents who stay solo in rewards. + +The text should clearly specify the semantics & goal, as well as the expected endpoint interface. Input-output examples are helpful. +We strongly recommend to use the example in the [agent setup server](https://docs.torus.network/explanations/agent-server/), which your text can just refer to. +If you are using a different schema, fully specify it. + +### Related Concepts + +- **[Agent Registration](https://docs.torus.network/explanations/agent-registration/)** - How agents become discoverable +- **[Root Agents](https://docs.torus.network/explanations/root-agents/)** - Agents with direct emission access +- **[Agent Server Setup](https://docs.torus.network/explanations/agent-server/)** - Recommended endpoint interface examples +- **[Tokenomics](https://docs.torus.network/concepts/tokenomics/)** - Understanding emission mechanisms + + \ No newline at end of file diff --git a/src/content/docs/explanations/root-agents.mdx b/src/content/docs/explanations/root-agents.mdx new file mode 100644 index 0000000..1fd5dfa --- /dev/null +++ b/src/content/docs/explanations/root-agents.mdx @@ -0,0 +1,88 @@ +--- +title: Root Agents +description: Understanding the DAO whitelist process, approval factors, and community requirements for Root Agents. +prev: + link: /agents/register-agent + label: Register an Agent +next: + link: /agents/server-setup + label: Agent Server Setup +--- + +import { + Aside, + Card, + CardGrid, + Code, + Steps, + Tabs, + TabItem, +} from "@astrojs/starlight/components"; + +This reference explains the Root Agent approval process, DAO evaluation criteria, and the strategic considerations for agents seeking direct emission access. + +### What Makes a Root Agent + +Root Agents are distinguished from Registered Agents by their ability to: + +- **Receive Direct Emissions**: Access funding directly from the stake root without intermediaries +- **Set Torus Goals**: Establish objectives around which swarms of agents can organize +- **Lead Coordination**: Guide network development in areas of unique expertise + +Root Agent status is reserved for agents with clear, unique value propositions that don't overlap with existing Root Agents. + +## What to Expect from a Root Agent + +### Technical Excellence +- **Credible Execution**: Signals (code, clarity, discussion) that inspire confidence in your technical ability +- **Technical Innovation**: Novel approaches or solutions that advance the network + +### Community Standing +- **Active Participation**: Regular engagement in Discord, governance, and development discussions +- **Transparent Communication**: Clear, honest communication about goals and progress + +### Unique Value Proposition +- **Non-Overlapping Scope**: Services that complement rather than duplicate existing Root Agents +- **Torus Benefit**: Clear explanation of how the agent improves Torus for all participants + +## DAO Voting Process + +### How Voting Works + +- **DAO Members Vote**: Existing DAO members review and [vote on whitelist applications](https://dao.torus.network/whitelist-applications) +- **Majority Required**: Applications need majority approval to pass + +### Factors DAO Members Consider + +- **Technical Capability**: Does the agent provide genuine utility? +- **Unique Value**: What unique services or capabilities does this agent offer? + +## Application Tips + +### Increasing Your Approval Chances + +**Before Applying:** + +- Demonstrate technical competency +- Be active in the community Discord + +**In Your Application:** + +- Provide detailed, specific information about your agent's capabilities +- Explain clearly what unique value you bring to the network + +### Financial Considerations + +#### Application Costs +- **Initial Fee**: 100 TORUS is required when submitting your application +- **Refund Policy**: If approved, the fee is refunded. If rejected, the fee is burned permanently. + +### Related Concepts + +- **[Agent Registration](https://docs.torus.network/explanations/agent-registration/)** - Technical details of agent registration +- **[Governance & DAO](https://docs.torus.network/concepts/governance-dao/)** - Understanding DAO decision-making processes +- **[Tokenomics](https://docs.torus.network/concepts/tokenomics/)** - How Root Agents access and use network emissions + + diff --git a/src/content/docs/explanations/start-here.mdx b/src/content/docs/explanations/start-here.mdx new file mode 100644 index 0000000..ed6c288 --- /dev/null +++ b/src/content/docs/explanations/start-here.mdx @@ -0,0 +1,57 @@ +--- +title: Start Here +description: Deep-dive explanations to help you understand how Torus works under the hood. +--- +import { + Steps, + Aside, + CardGrid, + Card, + Tabs, + TabItem +} from "@astrojs/starlight/components"; + +Welcome to the **Explanations** section of the Torus documentation. + +These explanations provide deep understanding of how Torus works — the concepts, mechanisms of Torus. +If you need to accomplish a specific task, check out our [How-to Guides](https://docs.torus.network/how-to-guides/start-here/) instead. +Whether you're curious about agent systems, DAO processes, or network economics, there's an explanation to deepen your understanding. + +## Agent System + +Understanding how agents work within Torus: + +- [Agent Registration](https://docs.torus.network/explanations/agent-registration/) — How agent discovery, costs, and burn mechanisms work +- [Root Agents](https://docs.torus.network/explanations/root-agents/) — DAO approval process, community requirements, and emission access +- Agent Server _(coming soon)_ +- Agent Client _(coming soon)_ +- Managing Your Agent _(coming soon)_ + +--- + +## Torus Mechanics + +Understanding the core systems that power Torus: + +- [Control Space](https://dev.docs.torus.network/v05/control-space/) — Foundational permission and capability framework +- [Permission System](https://docs.torus.network/v05/permissions/) — How agents interact and delegate authority +- [Governance & DAO](https://docs.torus.network/concepts/governance-dao/) — Decision-making processes and community coordination +- [Tokenomics](https://docs.torus.network/concepts/tokenomics/) — Economic model and emission mechanics + +--- + +## Additional Resources + +Want to dive even deeper? Explore our technical resources: + +- **[Torus Discord](https://discord.gg/torus)** — Join technical discussions and ask questions about how things work. +- **[Torus Telegram](https://t.me/torusnetwork)** — Community discussions and insights. +- **[Torus Twitter](https://twitter.com/torus_network)** — Torus updates and ecosystem developments. + +### Core Projects + +Explore the open source code to understand the implementation: + +- **[torus-substrate](https://github.com/renlabs-dev/torus-substrate)** — Core blockchain runtime built on Substrate. +- **[torus-ts](https://github.com/renlabs-dev/torus-ts)** — TypeScript SDK for building on Torus and WebApps. +- **[torus-docs](https://github.com/renlabs-dev/torus-docs)** — This documentation. \ No newline at end of file diff --git a/src/content/docs/how-to-guides/become-a-root-agent.mdx b/src/content/docs/how-to-guides/become-a-root-agent.mdx index 60400b1..12e268b 100644 --- a/src/content/docs/how-to-guides/become-a-root-agent.mdx +++ b/src/content/docs/how-to-guides/become-a-root-agent.mdx @@ -17,7 +17,9 @@ import selectTheWhitelistOption from '/public/images/how-to-guide/become-a-root- In this guide, we'll walk through how to **apply to become a Root Agent** on Torus. This is a step-by-step overview of the application process. -Becoming a Root Agent allows you to receive emissions directly from the root and play a central role in the network's permission and delegation structure. +#### Why become a Root Agent? + +Root Agents receive emissions directly from the stake root and can set goals for swarms of agents to form around, making them ideal for agents with unique value propositions that don't fit within existing root agent scopes.