diff --git a/astro.config.mjs b/astro.config.mjs index dfe311b..cc35bf9 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -25,12 +25,10 @@ export default defineConfig({ { label: "Getting Started", items: [ - { label: "Introduction", slug: "index" }, - { label: "Tokenomics", slug: "concepts/tokenomics" }, - { - label: "Concepts & Terminology", - slug: "getting-started/concepts", - }, + { label: "Welcome", slug: "index" }, + { label: "Tokenomics", slug: "getting-started/tokenomics" }, + { label: "Concepts & Terminology", slug: "getting-started/concepts-terminology" }, + { label: "Understanding Torus", slug: "getting-started/concepts" }, ], }, { @@ -40,14 +38,14 @@ export default defineConfig({ { label: "v0.5", items: [ - { label: "Control Space", slug: "v05/control-space" }, - { label: "Permission System", slug: "v05/permissions" }, + { label: "Control Space", slug: "explanations/v05/control-space" }, + { label: "Permission System", slug: "explanations/v05/permissions" }, { label: "Capability Permissions", - slug: "v05/capability-permissions", + slug: "explanations/v05/capability-permissions", }, - { label: "Emission Permissions", slug: "v05/emission-permissions" }, - { label: "Governance & DAO", slug: "concepts/governance-dao" }, + { label: "Emission Permissions", slug: "explanations/v05/emission-permissions" }, + { label: "Governance & DAO", slug: "explanations/v05/governance-dao" }, ], }, { @@ -55,14 +53,14 @@ export default defineConfig({ collapsed: false, items: [ { label: "Agent Registration", slug: "explanations/builders/agent-registration" }, - { label: "Agent Server", slug: "explanations/builders/agent-server" }, - { label: "Agent Client", slug: "explanations/builders/agent-client" }, { label: "Agent Editing", slug: "explanations/builders/agent-editing" }, { label: "Demand Signaling", slug: "explanations/builders/demand-signaling" }, + { label: "Agent Server", slug: "explanations/builders/agent-server" }, + { label: "Agent Client", slug: "explanations/builders/agent-client" }, ], }, { - label: "Leaders", + label: "Goal Leaders", collapsed: false, items: [ { label: "Root Agents", slug: "explanations/root-agents/root-agents" }, @@ -78,19 +76,21 @@ export default defineConfig({ label: "Holders", collapsed: false, items: [ - { label: "Setup a Wallet", slug: "how-to-guides/participants/setup-a-wallet" }, - { label: "Bridge from Base", slug: "how-to-guides/participants/bridge-from-base" }, - { label: "Stake your Torus", slug: "how-to-guides/participants/stake-your-torus" }, + { label: "Setup a Wallet", slug: "how-to-guides/holders/setup-a-wallet" }, + { label: "Bridge from Base", slug: "how-to-guides/holders/bridge-from-base" }, + { label: "Stake your Torus", slug: "how-to-guides/holders/stake-your-torus" }, ], }, { label: "Builders", collapsed: false, items: [ - { label: "Setup CLI", slug: "how-to-guides/builders/setup-cli" }, { label: "Register an Agent", slug: "how-to-guides/builders/register-an-agent" }, { label: "Edit your Agent", slug: "how-to-guides/builders/edit-your-agent" }, + { label: "Manage Capabilities", slug: "how-to-guides/builders/manage-capabilities" }, { label: "Create a Signal", slug: "how-to-guides/builders/create-signal" }, + // { label: "Manage Permissions", slug: "how-to-guides/builders/manage-permissions" }, + // { label: "Delegate Emission Streams", slug: "how-to-guides/builders/delegate-emission-streams" }, { label: "Setup Agent Server", slug: "how-to-guides/builders/setup-agent-server" }, { label: "Setup Agent Client", slug: "how-to-guides/builders/setup-agent-client" }, ], @@ -104,33 +104,40 @@ export default defineConfig({ }, ], }, - { - label: "CLI & Tools", - items: [ - { label: "Key Management", slug: "cli/key-management" }, - { label: "Balance Operations", slug: "cli/balance-operations" }, - ], - }, { label: "Development", items: [ + { label: "Start Here", slug: "development/start-here" }, { - label: "Web Apps Overview and Setup", - slug: "development/web-apps-overview-and-setup", + label: "Web Apps", + collapsed: false, + items: [ + { + label: "Overview and Setup", + slug: "development/web/overview-and-setup", + }, + { + label: "Querying Data", + slug: "development/web/querying-data", + }, + ], }, { - label: "Querying Data", - slug: "development/querying-data", + label: "CLI Reference", + collapsed: false, + items: [ + { label: "Setup CLI", slug: "development/cli/setup-cli" }, + { label: "Key Management", slug: "development/cli/key-management" }, + { label: "Balance Operations", slug: "development/cli/balance-operations" }, + ], }, - ], - }, - { - label: "Network Operations", - items: [ - { label: "Global Parameters", slug: "network/global-parameters" }, { - label: "Running a Node", - slug: "network/running-node", + label: "Network Operations", + collapsed: false, + items: [ + { label: "Global Parameters", slug: "development/network/global-parameters" }, + { label: "Running a Node", slug: "development/network/running-node" }, + ], }, ], }, diff --git a/public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png b/public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png new file mode 100644 index 0000000..8754c3d Binary files /dev/null and b/public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png differ diff --git a/public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png b/public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png new file mode 100644 index 0000000..8b8d66d Binary files /dev/null and b/public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png differ diff --git a/src/components/RedText.astro b/src/components/RedText.astro new file mode 100644 index 0000000..55282b6 --- /dev/null +++ b/src/components/RedText.astro @@ -0,0 +1,18 @@ +--- +export interface Props { + variant?: 'attention' | 'light' | 'soft'; + class?: string; +} + +const { variant = 'light', class: className = '' } = Astro.props; + +const variantClasses = { + attention: 'text-red-attention', + light: 'text-red-light', + soft: 'text-red-soft' +}; + +const redClass = variantClasses[variant]; +--- + + \ No newline at end of file diff --git a/src/content/docs/concepts/agents.mdx b/src/content/docs/concepts/agents.mdx deleted file mode 100644 index 6d28f40..0000000 --- a/src/content/docs/concepts/agents.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: What are Agents -description: Learn what an agent is in Torus. ---- - -import { CardGrid, LinkCard } from "@astrojs/starlight/components"; - -Agents are the same primitive in the blockchain but differ in their offchain role. -Both are registered keys, paired with an offchain object, able to receive weights by the allocator, determining their share in the emissions. - -This primitive separates all computation from the chain and allows agents to be arbitrarily complex and computationally expensive. - -**Agents are entities, either autonomous or human, that perform actions that align with Torus interests.** - - - - - diff --git a/src/content/docs/concepts/network-overview.mdx b/src/content/docs/concepts/network-overview.mdx deleted file mode 100644 index a2066ac..0000000 --- a/src/content/docs/concepts/network-overview.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Mainnet Concepts & Terminology -description: Learn the basic concepts and terminology of Torus. ---- - -import { - CardGrid, - LinkCard, - Aside, - Steps, -} from "@astrojs/starlight/components"; - - -### Network -The network consists of a dynamic set of registered agents competing to attract incentive from the allocator to earn TORUS. Incentives are weight-based, representing share in the continuous emission distribution. - -### Agent - -An agent is a key registered to the network, paired with an off-chain entity, either autonomous or human, that performs actions that align with Torus interests. - -### Allocator - -The allocator is a permissionless web platform maintained by _Renlabs_, enabling stakeholders to allocate incentive weights among agents. Users delegate TORUS to the allocator key, setting weights with their stake through the platform to receive dividends. - -### Curator - -The curator serves as the regulatory entity of the network, overseeing the agent and incentive landscape to ensure alignment with protocol interests. The curator has two primary permissions: - - - -1. **Managing the Agent Whitelist:** Approving agents to join the network and removing those that become misaligned. - -2. **Applying Penalty Factors:** Issuing penalties on agents that scale both the agent's incentives and the dividends of users who set weights on them. This mechanism helps correct and penalize over-incentivization, leveraging common sense to detect misalignment. - - - -The curator's decision-making system operates off-chain and is adaptable, functioning as an agent, a DAO or a trusted community member. - -Multiple specialized curators can operate in parallel, each permissioned by the root curator. The root curator can itself be replaced by the Torus DAO at any time. - -### Torus DAO - -The Torus DAO is a fully on-chain, TORUS stake-based governance system, managing the protocol through community proposals. It can modify network parameters, dynamically adjust emission rate, and allocate resources between the network and treasury to align with TORUS interests. - -### Torus treasury - -The treasury is a DAO-owned key that accumulates emissions and receives transfers. Treasury funds are managed via DAO proposals to support ecosystem initiatives. - -### Weights - -Weights provide an expressive format for granularly representing the relative value of agents within the network, guiding the distribution of incentives. For example, an agent with a weight of 0.01 holds a 1% share of the total incentives being continuously distributed. - - - - - diff --git a/src/content/docs/cli/balance-operations.mdx b/src/content/docs/development/cli/balance-operations.mdx similarity index 95% rename from src/content/docs/cli/balance-operations.mdx rename to src/content/docs/development/cli/balance-operations.mdx index 8119f21..04b4752 100644 --- a/src/content/docs/cli/balance-operations.mdx +++ b/src/content/docs/development/cli/balance-operations.mdx @@ -43,4 +43,4 @@ The unstaking command is defined as follows: torus balance unstake ``` -You can also specify the name of the key, if it's located on your disk. Same as in transferring or staking. +You can also specify the name of the key, if it's located on your disk. Same as in transferring or staking. \ No newline at end of file diff --git a/src/content/docs/cli/key-management.mdx b/src/content/docs/development/cli/key-management.mdx similarity index 94% rename from src/content/docs/cli/key-management.mdx rename to src/content/docs/development/cli/key-management.mdx index bb11326..86de96a 100644 --- a/src/content/docs/cli/key-management.mdx +++ b/src/content/docs/development/cli/key-management.mdx @@ -45,7 +45,7 @@ This command displays both public and private key details, ensuring you have acc To list all keys stored on your system, execute: ```sh -# Lists the names and addresses of keys stored on disk. +# Lists the names and addresses of keys stored on disk. torus key list ``` @@ -69,4 +69,4 @@ You can also sort the balance by **all, free, staked** (default all summed balan torus key balances --sort-balance free ``` -Will return the keys sorted by their free balance. +Will return the keys sorted by their free balance. \ No newline at end of file diff --git a/src/content/docs/how-to-guides/builders/setup-cli.mdx b/src/content/docs/development/cli/setup-cli.mdx similarity index 85% rename from src/content/docs/how-to-guides/builders/setup-cli.mdx rename to src/content/docs/development/cli/setup-cli.mdx index 4d76c12..f039236 100644 --- a/src/content/docs/how-to-guides/builders/setup-cli.mdx +++ b/src/content/docs/development/cli/setup-cli.mdx @@ -110,8 +110,6 @@ The CLI enables developers and power users to manage Torus operations from the c -{/* - ## Basic CLI Usage Now that you have the CLI installed, here are the main command categories: @@ -139,10 +137,10 @@ torus misc circulating-supply # Total supply info Now that you have the CLI set up, you can: -- **Register an agent**: Use [agent registration](https://docs.torus.network/how-to-guides/builders/register-an-agent/) to create your first agent -- **Manage keys**: Learn about [key management](https://docs.torus.network/cli/key-management/) for secure operations -- **Check balances**: Use [balance operations](https://docs.torus.network/cli/balance-operations/) to monitor your tokens -- **Build integrations**: Set up [agent servers](https://docs.torus.network/how-to-guides/builders/setup-agent-server/) for programmatic interactions +- **Register an agent**: Use [agent registration](/how-to-guides/builders/register-an-agent/) to create your first agent +- **Manage keys**: Learn about [key management](/development/cli/key-management/) for secure operations +- **Check balances**: Use [balance operations](/development/cli/balance-operations/) to monitor your tokens +- **Build integrations**: Set up [agent servers](/how-to-guides/builders/setup-agent-server/) for programmatic interactions Connect with the community: - [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements @@ -155,9 +153,9 @@ Now that you have the CLI set up, you can: - Learn to create and manage your keys + Learn to create and manage your keys - Transfer tokens and manage staking + Transfer tokens and manage staking - */} \ No newline at end of file + \ No newline at end of file diff --git a/src/content/docs/network/global-parameters.mdx b/src/content/docs/development/network/global-parameters.mdx similarity index 99% rename from src/content/docs/network/global-parameters.mdx rename to src/content/docs/development/network/global-parameters.mdx index 623e3d4..64a08af 100644 --- a/src/content/docs/network/global-parameters.mdx +++ b/src/content/docs/development/network/global-parameters.mdx @@ -86,4 +86,4 @@ You can query all of these global parameters using CLI: ```bash torus network params -``` +``` \ No newline at end of file diff --git a/src/content/docs/network/running-node.mdx b/src/content/docs/development/network/running-node.mdx similarity index 98% rename from src/content/docs/network/running-node.mdx rename to src/content/docs/development/network/running-node.mdx index d43fa18..fcab94c 100644 --- a/src/content/docs/network/running-node.mdx +++ b/src/content/docs/development/network/running-node.mdx @@ -85,4 +85,4 @@ cargo xtask run local --alice ## Additional Information -- You can customize your node's configuration by modifying the appropriate files in the project. +- You can customize your node's configuration by modifying the appropriate files in the project. \ No newline at end of file diff --git a/src/content/docs/development/start-here.mdx b/src/content/docs/development/start-here.mdx new file mode 100644 index 0000000..28929a7 --- /dev/null +++ b/src/content/docs/development/start-here.mdx @@ -0,0 +1,60 @@ +--- +title: Start Here +description: Technical documentation and tools for developing with and on Torus. +--- +import { + Steps, + Aside, + CardGrid, + Card, + Tabs, + TabItem +} from "@astrojs/starlight/components"; + +Welcome to the **Development** section of the Torus documentation. + +This section provides comprehensive technical resources for developers building with Torus — from setting up development environments to running nodes and managing keys. +Whether you're integrating with existing web apps, querying data, or running your own infrastructure, you'll find the technical details here. + +## Web Application Development + +Building and integrating with the Torus ecosystem: + +- [Overview and Setup](https://docs.torus.network/development/web/overview-and-setup/) — Setting up the development environment and understanding the monorepo structure +- [Querying Data](https://docs.torus.network/development/web/querying-data/) — API operations for retrieving stake allocation and network data + +--- + +## CLI & Tools + +Command-line operations for key and balance management: + +- [Key Management](https://docs.torus.network/development/cli/key-management/) — Creating, importing, and managing cryptographic keys +- [Balance Operations](https://docs.torus.network/development/cli/balance-operations/) — Transferring and staking operations via CLI + +--- + +## Network Infrastructure + +Running and configuring Torus network infrastructure: + +- [Global Parameters](https://docs.torus.network/development/network/global-parameters/) — Understanding and configuring blockchain parameters +- [Running a Node](https://docs.torus.network/development/network/running-node/) — Setting up and operating a Torus Substrate node + +--- + +## Questions Not Covered Here? + +Need help with development tasks? The community is here to help: + +- **[Discord](https://discord.gg/torus)** — Technical discussions, support, and announcements +- **[Telegram](https://t.me/torusnetwork)** — General chat and announcements +- **[Twitter](https://x.com/torus_network)** — Updates and ecosystem news + +### Core Projects + +Explore the open source code to understand implementation details: + +- **[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/development/web-apps-install-and-run(old).mdx b/src/content/docs/development/web-apps-install-and-run(old).mdx deleted file mode 100644 index 8c3af0b..0000000 --- a/src/content/docs/development/web-apps-install-and-run(old).mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Web Apps Install and Run -description: Learn how to install and run the torus-ts ---- - -import { - Badge, - Steps, - Tabs, - TabItem, - Aside, -} from "@astrojs/starlight/components"; - -This guide will walk you through the process of installing and running the `torus-ts` monorepo. - -## Prerequisites - -- **Node.js** - `20.16.0` or higher. -- **PNPM** - `9.7.1` or higher. -- **Docker** - [installation guide](https://docs.docker.com/get-docker/). -- **Just** - [installation guide](https://github.com/casey/just). - -##### Docker Tip - -If you have difficulties or want alternatives to simplify using Docker, consider: - -- [Colima](https://github.com/abiosoft/colima): A lightweight solution for running containers on macOS. -- [Orbstack](https://orbstack.dev/): A fast and efficient alternative for managing containers. - -## Monorepo setup - -
- - - -1. ##### Clone the repository - - - - ```bash git clone git@github.com:renlabs-dev/torus-ts.git ``` Clone - using the web URL. - - - ```bash https://github.com/renlabs-dev/torus-ts.git ``` Use a - password-protected SSH key. - - - ```bash gh repo clone renlabs-dev/torus-ts ``` Use the [GitHub - CLI](https://cli.github.com/). - - - -
- -2. ##### Install the dependencies - - ```bash - pnpm install - # or - just install - ``` - -
- -3. ##### Configure environment variables - - There is an `.env.example` in the root directory you can use for reference - - ```bash - cp .env.example .env - ``` - -
- -4. ##### Setup database - - - - Create a postgres container with docker: - - ```bash - docker run --name torus-db-container \ - -e POSTGRES_PASSWORD=password \ - -e POSTGRES_DB=torus-ts-db \ - -e POSTGRES_USER=postgres \ - -p 1337:1337 \ - -d postgres:16-alpine \ - postgres -p 1337 - ``` - - Push the Drizzle schema to the database: - - ```bash - just db-push - ``` - - You can also use the `just db-studio` command to open a GUI provided by [Drizzle](https://orm.drizzle.team/drizzle-studio/overview). - -
- -5. ##### Build the project - - ```bash - just build - ``` - - - -
- -6. ##### Run the project - - From the root directory, run the following command: - - ```bash - just dev - ``` - - - - From the app directory, run the following command: - - ```bash - pnpm run dev - ``` - - - -
- - - - diff --git a/src/content/docs/development/web-apps-overview(old).mdx b/src/content/docs/development/web-apps-overview(old).mdx deleted file mode 100644 index d5a2046..0000000 --- a/src/content/docs/development/web-apps-overview(old).mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Introduction -description: Learn how to build into Torus typescript ecosystem ---- - -import { LinkCard, Aside } from "@astrojs/starlight/components"; - -These docs will guide you through the process of building / integrating with Torus web apps. We provide a set of tools and libraries to help you build and contribute to the Torus ecosystem. - -The ecosystem is built using a monorepo with [Turborepo](https://turbo.build/repo/docs), which allows us to share code and tools across different projects. - -## Web Apps - - - - - - - - - diff --git a/src/content/docs/development/web-apps-overview-and-setup.mdx b/src/content/docs/development/web/overview-and-setup.mdx similarity index 97% rename from src/content/docs/development/web-apps-overview-and-setup.mdx rename to src/content/docs/development/web/overview-and-setup.mdx index 131b745..41e1700 100644 --- a/src/content/docs/development/web-apps-overview-and-setup.mdx +++ b/src/content/docs/development/web/overview-and-setup.mdx @@ -18,7 +18,7 @@ The ecosystem is built using a monorepo with [Turborepo](https://turbo.build/rep ## Prerequisites @@ -53,7 +53,7 @@ For detailed setup instructions, see the setup guide below. diff --git a/src/content/docs/development/querying-data.mdx b/src/content/docs/development/web/querying-data.mdx similarity index 77% rename from src/content/docs/development/querying-data.mdx rename to src/content/docs/development/web/querying-data.mdx index 362ef0b..0d51fd8 100644 --- a/src/content/docs/development/querying-data.mdx +++ b/src/content/docs/development/web/querying-data.mdx @@ -6,7 +6,7 @@ description: Learn how to query the stake weight between keys import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"; Our API allows you to retrieve information about the stake allocation between keys and agents. -You can query this data by making a GET request to: `https://allocator.torus.network/api/allocated-weight`. +You can query this data by making a GET request to: `https://portal.torus.network/api/allocated-weight`. ## API Response Format @@ -29,14 +29,14 @@ The API response has the following structure: To filter the response for a specific allocating key, append the userKey query parameter to the API endpoint: - ```allocator.torus.network/api/allocated-weight?userKey=``` + ```portal.torus.network/api/allocated-weight?userKey=``` - Filter by Agent Key To filter the response for specific agents, append the agentKey query parameter to the API endpoint: - ```allocator.torus.network/api/allocated-weight?agentKey=``` + ```portal.torus.network/api/allocated-weight?agentKey=``` + \ No newline at end of file diff --git a/src/content/docs/explanations/builders/agent-registration.mdx b/src/content/docs/explanations/builders/agent-registration.mdx index cb789cb..937d708 100644 --- a/src/content/docs/explanations/builders/agent-registration.mdx +++ b/src/content/docs/explanations/builders/agent-registration.mdx @@ -17,6 +17,14 @@ import { Agent registration in Torus creates discoverable entities that can receive, create, and delegate permissions within the network. Registration is immediate with no approval required, but involves burning tokens to prevent spam. + + ### Registration Economics Agent registration requires permanently burning tokens: @@ -30,15 +38,15 @@ The burn mechanism maintains network quality by creating economic barriers to sp ### Discovery and Capabilities -Registered agents become discoverable through the public agent registry and can be viewed on the [Allocator page](https://allocator.torus.network/). +Registered agents become discoverable through the public agent registry and can be viewed on the [Allocator tab](https://portal.torus.network/root-allocator). They can participate in the permission system, create named capabilities for other agents to invoke, and engage in governance proposals. Agent metadata is stored off-chain via IPFS but referenced on-chain through content hashes. ### Related Concepts - **[Root Agents](https://docs.torus.network/explanations/root-agents/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 +- **[Permission System](https://docs.torus.network/explanations/v05/permissions/)** - How agents interact and delegate authority +- **[Governance & DAO](https://docs.torus.network/explanations/v05/governance-dao/)** - Understanding DAO decision-making processes