diff --git a/astro.config.mjs b/astro.config.mjs index 15cf150..16e6186 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -26,9 +26,7 @@ export default defineConfig({ label: "Getting Started", items: [ { 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" }, + { label: "Understanding Torus", slug: "getting-started/understanding-torus" }, ], }, { @@ -53,6 +51,8 @@ export default defineConfig({ label: "Holders", collapsed: true, items: [ + + { label: "Tokenomics", slug: "explanations/holders/tokenomics" }, { label: "Staking", slug: "explanations/holders/staking" }, ], }, @@ -75,6 +75,7 @@ export default defineConfig({ { label: "Emission Proposals", slug: "explanations/goal-leaders/emission-proposals" }, ], }, + { label: "Concepts & Terminology", slug: "explanations/concepts-terminology" }, ], }, { @@ -151,6 +152,9 @@ export default defineConfig({ ], }, ], + components: { + Head: './src/components/Head.astro', + }, customCss: ["./src/tailwind.css"], }), tailwind({ applyBaseStyles: false }), diff --git a/package.json b/package.json index 6290896..6600755 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "@astrojs/starlight-tailwind": "^3.0.0", "@astrojs/tailwind": "^6.0.0", "astro": "^5.3.0", + "astro-tooltips": "^0.6.2", "tailwindcss": "^3.4.4", "typescript": "^5.7.2" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0cd982e..ef5cb72 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -23,6 +23,9 @@ importers: astro: specifier: ^5.3.0 version: 5.3.0(jiti@1.21.6)(rollup@4.34.6)(typescript@5.7.2)(yaml@2.6.1) + astro-tooltips: + specifier: ^0.6.2 + version: 0.6.2 tailwindcss: specifier: ^3.4.4 version: 3.4.15 @@ -493,6 +496,9 @@ packages: resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==} engines: {node: '>=14'} + '@popperjs/core@2.11.8': + resolution: {integrity: sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A==} + '@rollup/pluginutils@5.1.4': resolution: {integrity: sha512-USm05zrsFxYLPdWWq+K3STlWiT/3ELn3RcV5hJMghpeAIhxfsUIg6mt12CBJBInWMV4VneoV7SfGv8xIwo2qNQ==} engines: {node: '>=14.0.0'} @@ -756,6 +762,9 @@ packages: peerDependencies: astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0 + astro-tooltips@0.6.2: + resolution: {integrity: sha512-I9uXbchctnRqbc0mnxKcBRfweMuql/U+619+MzNvq3kANc7xthOXj6cMNgAkTaXoHJLdFMKL3Fx6vB5cyiiRXg==} + astro@5.3.0: resolution: {integrity: sha512-e88l/Yk/6enR/ZDddLbqtM+oblBFk5mneNSmNesyVYGL/6Dj4UA67GPAZOk79VxT5dbLlclZSyyw/wlxN1aj3A==} engines: {node: ^18.17.1 || ^20.3.0 || >=22.0.0, npm: '>=9.6.5', pnpm: '>=7.1.0'} @@ -2005,6 +2014,9 @@ packages: tinyexec@0.3.2: resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==} + tippy.js@6.3.7: + resolution: {integrity: sha512-E1d3oP2emgJ9dRQZdf3Kkn0qJgI6ZLpyS5z6ZkY1DF3kaQaBsGZsndEpHwx+eC+tYM41HaSNvNtLx8tU57FzTQ==} + to-regex-range@5.0.1: resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} engines: {node: '>=8.0'} @@ -2881,6 +2893,8 @@ snapshots: '@pkgjs/parseargs@0.11.0': optional: true + '@popperjs/core@2.11.8': {} + '@rollup/pluginutils@5.1.4(rollup@4.34.6)': dependencies: '@types/estree': 1.0.6 @@ -3130,6 +3144,10 @@ snapshots: astro: 5.3.0(jiti@1.21.6)(rollup@4.34.6)(typescript@5.7.2)(yaml@2.6.1) rehype-expressive-code: 0.40.2 + astro-tooltips@0.6.2: + dependencies: + tippy.js: 6.3.7 + astro@5.3.0(jiti@1.21.6)(rollup@4.34.6)(typescript@5.7.2)(yaml@2.6.1): dependencies: '@astrojs/compiler': 2.10.3 @@ -5021,6 +5039,10 @@ snapshots: tinyexec@0.3.2: {} + tippy.js@6.3.7: + dependencies: + '@popperjs/core': 2.11.8 + to-regex-range@5.0.1: dependencies: is-number: 7.0.0 diff --git a/src/components/Head.astro b/src/components/Head.astro new file mode 100644 index 0000000..c85e59a --- /dev/null +++ b/src/components/Head.astro @@ -0,0 +1,8 @@ +--- +import type { Props } from '@astrojs/starlight/props'; +import StarlightHead from '@astrojs/starlight/components/Head.astro'; +import { Tooltips } from 'astro-tooltips'; +--- + + + \ No newline at end of file diff --git a/src/content/docs/explanations/concepts-terminology.mdx b/src/content/docs/explanations/concepts-terminology.mdx new file mode 100644 index 0000000..387dd1c --- /dev/null +++ b/src/content/docs/explanations/concepts-terminology.mdx @@ -0,0 +1,191 @@ +--- +title: Concepts & Terminology +description: Key terms and concepts used throughout the Torus ecosystem +--- + +import { Aside } from "@astrojs/starlight/components"; + +export const DEFINITIONS = { + // Core Concepts + agent: `An autonomous entity in Torus 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.`, + + swarm: `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.`, + + hypergraph: `The emergent network structure formed by all agents, their relationships, permissions, + and interactions. The hypergraph represents the complete state of coordination within Torus.`, + + rootAgent: `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.`, + + // Permissions & Capabilities + capability: `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.`, + + permission: `The right to use or delegate a specific capability. Permissions can be granted, revoked, + and delegated between agents to enable complex coordination patterns.`, + + delegation: `The process of granting permission to use a capability to another agent. Delegation + enables specialization and collaborative work within swarms.`, + + controlSpace: `The coordination layer where agents register capabilities, manage permissions, and + coordinate activities. It serves as the control plane for the entire network.`, + + // Economic Terms + torusToken: `The native token of Torus used for staking, governance, and accessing + network services.`, + + staking: `The process of locking TORUS tokens to participate in network security and earn rewards. + Staked tokens can be allocated to support specific agents.`, + + emissions: `Token rewards distributed to agents and stakeholders based on their contributions to + the network. Emissions flow from root agents to the broader ecosystem.`, + + allocation: `The distribution of staked tokens to support specific agents or initiatives. Allocations + determine how emissions flow through the network.`, + + // Technical Terms + agentServer: `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.`, + + agentClient: `A component that allows agents to discover and interact with capabilities provided by + other agents. Clients handle authentication and communication protocols.`, + + signal: `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.`, + + substrate: `The blockchain framework that powers Torus. Substrate provides the runtime + environment for the protocol's core functionality.`, + + // Governance Terms + dao: `The governance structure through which major protocol decisions are made. Torus DAO + enables stakeholder participation in network evolution.`, + + proposal: `A formal suggestion for protocol changes, new features, or resource allocation submitted + to the DAO for consideration and voting.`, + + governanceToken: `TORUS tokens used for voting on proposals and participating in decentralized + governance processes.`, + + // ================= Compound Terms ================= + // Agent & Swarm together + agentSwarm: `A coordinated group of autonomous entities working together in Torus toward + a common goal, forming organically around specific objectives and operating at multiple scales.`, + + // Protocol & Architecture Terms + stakeBasedP2PProtocol: `A peer-to-peer network where participation and influence are determined by the amount of tokens locked (staked) in the system, ensuring aligned incentives among participants.`, + + fractalSuperSwarm: `A hierarchical structure where the entire system mirrors its own patterns at every scale. Smaller swarms within swarms, all following the same organizational principles.`, + + recursivelyDelegated: `A cascading permission system where agents can grant others the ability to further delegate their permissions, creating chains of trust and capability sharing.`, + + subgraph: `A smaller, self-contained network within the larger hypergraph that represents individual swarms and their internal relationships.`, + + stakeRoot: `The central origin point of the network's authority, derived from the collective stake of all token holders, serving as the ultimate source of permissions and incentives.`, + + // Coordination Terms + topDownGoals: `Objectives set by root agents or high-level stakeholders that cascade through the network, providing direction while allowing bottom-up implementation.`, + + selfAssemblingMultiScaleCompetencyArchitecture: `Autonomous structures that spontaneously organize at different levels of complexity, with each level capable of solving problems appropriate to its scale.`, + + openCompetitionAtEveryEdge: `A system where any connection between agents can be challenged or improved by alternative solutions, ensuring continuous optimization.`, + + recursiveNicheConstruction: `The iterative process where swarms create specialized roles and environments that enable further specialization, building increasingly sophisticated capabilities.`, + + granularSpecialization: `The ability for agents to develop deep expertise in very specific areas while maintaining connections to the broader network through the permission system.`, + + // Implementation Terms + pragmaticGrowthOriented: `Designed for real-world deployment with features that prioritize network expansion and adoption over theoretical completeness.`, + + battletesting: `Live deployment to stress-test concepts under real conditions with actual users and economic incentives.`, + + pureAndCompleteImplementation: `The final version that fully realizes all theoretical aspects of the Torus model without compromises made for initial deployment.`, + + + // General Technical Terms + recursive: `Recursive describes a process or definition that refers back to itself. + It works by applying the same rule to a simpler version of the original. + Each step breaks the problem into a smaller piece and repeats the same approach until it reaches that simplest instance.` + +}; + +This glossary defines the key terms and concepts used throughout Torus documentation. +Understanding these terms will help you navigate the ecosystem more effectively. + +## Core Concepts + +### Agent + {DEFINITIONS.agent} + +### Swarm + {DEFINITIONS.swarm} + +### Hypergraph + {DEFINITIONS.hypergraph} + +### Root Agent + {DEFINITIONS.rootAgent} + +### Recursive + {DEFINITIONS.recursive} + +## Permissions & Capabilities + +### Capability + {DEFINITIONS.capability} + +### Permission + {DEFINITIONS.permission} + +### Delegation + {DEFINITIONS.delegation} + +### Control Space + {DEFINITIONS.controlSpace} + +## Economic Terms + +### TORUS Token + {DEFINITIONS.torusToken} + +### Staking + {DEFINITIONS.staking} + +### Emissions + {DEFINITIONS.emissions} + +### Allocation + {DEFINITIONS.allocation} + +## Technical Terms + +### Agent Server + {DEFINITIONS.agentServer} + +### Agent Client + {DEFINITIONS.agentClient} + +### Signal + {DEFINITIONS.signal} + +### Substrate + {DEFINITIONS.substrate} + +## Governance Terms + +### DAO (Decentralized Autonomous Organization) + {DEFINITIONS.dao} + +### Proposal + {DEFINITIONS.proposal} + +### Governance Token + {DEFINITIONS.governanceToken} + + diff --git a/src/content/docs/getting-started/tokenomics.mdx b/src/content/docs/explanations/holders/tokenomics.mdx similarity index 100% rename from src/content/docs/getting-started/tokenomics.mdx rename to src/content/docs/explanations/holders/tokenomics.mdx diff --git a/src/content/docs/explanations/table-of-contents.mdx b/src/content/docs/explanations/table-of-contents.mdx index 26bab9f..3da74a2 100644 --- a/src/content/docs/explanations/table-of-contents.mdx +++ b/src/content/docs/explanations/table-of-contents.mdx @@ -31,9 +31,12 @@ Understanding the technical implementation and design of Torus v0.5: ## For Holders -Understanding how holders participate in the network: -- [Staking](https://docs.torus.network/explanations/holders/staking/) — Staking mechanisms, incentives, and reward distribution +Learn about TORUS economics and understand how you can participate: + +- [Tokenomics](https://docs.torus.network/explanations/holders/tokenomics/) — Economics of TORUS: supply mechanisms and emission distribution models +- [Staking](https://docs.torus.network/explanations/holders/staking/) — Staking mechanisms and incentives for network participation + --- diff --git a/src/content/docs/getting-started/concepts-terminology.mdx b/src/content/docs/getting-started/concepts-terminology.mdx deleted file mode 100644 index ea81f57..0000000 --- a/src/content/docs/getting-started/concepts-terminology.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Concepts & Terminology -description: Key terms and concepts used throughout the Torus ecosystem ---- - -import { Aside } from "@astrojs/starlight/components"; - - -This glossary defines the key terms and concepts used throughout Torus documentation. Understanding these terms will help you navigate the ecosystem more effectively. - -## Core Concepts - -### Agent -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. - -### Swarm -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. - -### Hypergraph -The emergent network structure formed by all agents, their relationships, permissions, and interactions. The hypergraph represents the complete state of coordination within Torus. - -### Root Agent -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. - -## Permissions & Capabilities - -### Capability -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. - -### Permission -The right to use or delegate a specific capability. Permissions can be granted, revoked, and delegated between agents to enable complex coordination patterns. - -### Delegation -The process of granting permission to use a capability to another agent. Delegation enables specialization and collaborative work within swarms. - -### Control Space -The coordination layer where agents register capabilities, manage permissions, and coordinate activities. It serves as the control plane for the entire network. - -## Economic Terms - -### TORUS Token -The native token of the Torus network used for staking, governance, and accessing network services. - -### Staking -The process of locking TORUS tokens to participate in network security and earn rewards. Staked tokens can be allocated to support specific agents. - -### Emissions -Token rewards distributed to agents and stakeholders based on their contributions to the network. Emissions flow from root agents to the broader ecosystem. - -### Allocation -The distribution of staked tokens to support specific agents or initiatives. Allocations determine how emissions flow through the network. - -## Technical Terms - -### Agent Server -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. - -### Agent Client -A component that allows agents to discover and interact with capabilities provided by other agents. Clients handle authentication and communication protocols. - -### Signal -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. - -### Substrate -The blockchain framework that powers the Torus network. Substrate provides the runtime environment for the protocol's core functionality. - -## Governance Terms - -### DAO (Decentralized Autonomous Organization) -The governance structure through which major protocol decisions are made. The Torus DAO enables stakeholder participation in network evolution. - -### Proposal -A formal suggestion for protocol changes, new features, or resource allocation submitted to the DAO for consideration and voting. - -### Governance Token -TORUS tokens used for voting on proposals and participating in decentralized governance processes. - - diff --git a/src/content/docs/getting-started/concepts.mdx b/src/content/docs/getting-started/understanding-torus.mdx similarity index 52% rename from src/content/docs/getting-started/concepts.mdx rename to src/content/docs/getting-started/understanding-torus.mdx index 775eb0e..b392aa0 100644 --- a/src/content/docs/getting-started/concepts.mdx +++ b/src/content/docs/getting-started/understanding-torus.mdx @@ -4,22 +4,26 @@ description: Layer1 self-assembling & self-optimizing autonomous super-swarm --- import { CardGrid, LinkCard, Aside } from "@astrojs/starlight/components"; +import { DEFINITIONS } from '../explanations/concepts-terminology.mdx'; # Layer1 self-assembling & self-optimizing autonomous super-swarm -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. +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 permission and incentives among agents. Swarms are subgraphs, and can form at any position in the hypergraph. -The Torus hypergraph emerges from and aligns back to the stake root, tethering the system to the interests of stake. +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. Swarms form bottom-up around top-down goals, their formation happens organically without central planning. -Swarms operate as self-assembling multi-scale competency architectures, +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. -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 swarm's goal. +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 swarm's goal. #### v0.5 diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 32665f0..ff5b275 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -38,8 +38,9 @@ Connect with the Torus community: ## Choose Your Path -This documentation is structured linearly, but you're free to explore it your way. +This guide adapts to your style, whether you prefer theory first or hands‑on learning. -You can start with Understanding the concepts or skip ahead to How it works. -If you choose Understanding the concepts, and then getting stuff done, -just follow the guide step-by-step using the Next button below. \ No newline at end of file +- Understanding the Concepts: Explore the key ideas, definitions, and background. +- [How-to guides](https://docs.torus.network/how-to-guides/table-of-contents): Jump straight into practical steps and examples. + +If you’d like a step-by‑step walkthrough, start with Understanding the Concepts and use the Next button at the bottom of each page to proceed. \ No newline at end of file diff --git a/src/tailwind.css b/src/tailwind.css index 5b4c599..0bb3e9b 100644 --- a/src/tailwind.css +++ b/src/tailwind.css @@ -28,6 +28,24 @@ details details .large { color: inherit !important; /* Remove test color */ } +/* +CONTENT LINK STYLING CUSTOMIZATION GUIDE: +This section controls the blue color for content links while preserving +navigation elements in their original colors. + +To customize content link colors: +- Change #3b82f6 (blue-500) for normal link color +- Change #2563eb (blue-600) for hover link color +- Add more selectors to include additional link types +- Add more exclusions to prevent styling specific elements + +Navigation elements excluded: +- Sidebar navigation +- Page navigation (prev/next buttons) +- Header navigation +- Any nav-specific elements +*/ + /* Make content hyperlinks blue, but keep navigation original colors */ @layer components { /* Only make content area links blue */ @@ -54,8 +72,9 @@ details details .large { } } -/* Explicitly keep sidebar navigation in original colors */ +/* Explicitly keep navigation elements in original colors */ @layer components { + /* Sidebar navigation */ nav a, nav .large, [data-starlight-sidebar] a, @@ -65,16 +84,32 @@ details details .large { details summary, details summary .large, .sidebar a, - .sidebar .large { + .sidebar .large, + /* Page navigation (prev/next buttons) */ + .pagination a, + [data-pagination] a, + .pagination-links a, + .sl-flex a[rel="prev"], + .sl-flex a[rel="next"], + footer a, + .starlight-aside .pagination a { color: inherit !important; text-decoration: none !important; } + /* Hover states for navigation elements */ nav a:hover, [data-starlight-sidebar] a:hover, nav[aria-labelledby="starlight__sidebar-navigation"] a:hover, details summary:hover, - .sidebar a:hover { + .sidebar a:hover, + .pagination a:hover, + [data-pagination] a:hover, + .pagination-links a:hover, + .sl-flex a[rel="prev"]:hover, + .sl-flex a[rel="next"]:hover, + footer a:hover, + .starlight-aside .pagination a:hover { color: inherit !important; text-decoration: none !important; } @@ -110,3 +145,57 @@ details details .large { font-weight: 500 !important; } } + +/* Make text with tooltips appear yellowish with underline */ +[title] { + color: #d97706 !important; /* Yellow-600 */ + /* text-decoration: underline; */ + /* text-decoration-style: dotted; */ + cursor: help; +} + +[title]:hover { + color: #b45309 !important; /* Yellow-700 - darker on hover */ + text-decoration-style: solid; +} + +/* +TOOLTIP STYLING CUSTOMIZATION GUIDE: +The astro-tooltips package uses Tippy.js under the hood. +You can customize the tooltip appearance by targeting these CSS classes: + +1. .tippy-box - Main tooltip container +2. .tippy-content - Content wrapper inside tooltip +3. .tippy-arrow - Tooltip arrow/pointer + +Available properties to customize: +- max-width: Controls tooltip width (forces line breaks) +- background-color: Tooltip background +- color: Text color +- padding: Inner spacing +- border-radius: Corner rounding +- font-size: Text size +- line-height: Line spacing +- box-shadow: Drop shadow +- border: Border styling +*/ + +/* Custom tooltip styling - square-ish with line breaks */ +.tippy-box { + max-width: 300px !important; /* Force line breaks at 300px */ + background-color: #374151 !important; /* Gray-700 background */ + border-radius: 6px !important; /* Slightly rounded corners for square-ish look */ + box-shadow: 0 4px 14px -2px rgba(0, 0, 0, 0.2) !important; +} + +.tippy-content { + padding: 12px 16px !important; /* More padding for better readability */ + color: #f9fafb !important; /* Gray-50 text */ + font-size: 14px !important; + line-height: 1.5 !important; /* Better line spacing */ + text-align: left !important; +} + +.tippy-arrow { + color: #374151 !important; /* Match background color */ +}