# Home

## Cortensor: Collaborative AI Frontier

Welcome to the official documentation for Cortensor, the pioneering decentralized AI inference and development platform. Here, you will find comprehensive resources to help you understand, set up, and maximize the potential of Cortensor.

### Overview

Cortensor aims to democratize AI by leveraging the power of decentralized networks and open-source models. By eliminating the constraints of centralized services, Cortensor provides a scalable, cost-effective solution for AI inference and development.

### Key Features

* **Decentralized AI Inference**: Harness the collective power of distributed computing for efficient and scalable AI processing.
* **Open-Source Models**: Utilize a variety of models for flexible and unrestricted AI applications.
* **Blockchain Integration**: Ensure secure, transparent transactions and incentivized collaborations.
* **Scalability and Efficiency**: Optimize resource usage and reduce operational costs.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.\
\
*<mark style="color:$warning;">**Important Notice**</mark>*

*<mark style="color:$warning;">Please be aware that the content may contain redundant and duplicate information, and many details are subject to change. Your understanding and patience are appreciated as we continue to improve and update this documentation.</mark>*


# Abstract

This document introduces "Cortensor," a groundbreaking decentralized AI inference protocol designed to meet the escalating demand for a neutral, trustless platform that can efficiently host and deliver services from advanced AI models, including DALL-E and GPT-4. As these models become increasingly specialized and integrated into various industries, the need for a system that ensures efficient, reliable, and secure AI service provisioning is becoming more critical.

Cortensor proposes a novel architecture that distinctly segregates data handling, control mechanisms, and transaction processing, enhancing the system's reliability, scalability, and transparency. At the core of Cortensor is the implementation of a dual validation system: "Proof of Inference" (PoI) and "Proof of Useful Work" (PoUW).

* **Proof of Inference (PoI):** PoI measures the accuracy of AI inferencing by comparing the outputs from different nodes using an additional LLM model. This validation is achieved through the analysis of embedding vector distances, ensuring that the AI-generated outputs are consistent and reliable across the network.
* **Proof of Useful Work (PoUW):** PoUW goes a step further by using an additional LLM model to validate the correctness and usefulness of the AI inferencing results. This process focuses on ensuring that the generated outputs are not only accurate but also contextually relevant and applicable, adding an extra layer of quality assurance.

These systems fortify the platform against adversarial behaviors, such as inadequate AI service provision, payment defaults, and the illicit replication of AI models. Integrated within the transaction layer, this approach, combined with the economic layer, manages billing, metering, and incentives within a blockchain framework, fostering a secure and dependable environment.

Cortensor leverages the decentralized nature of blockchain technology to establish a marketplace/orchestrator layer, enabling effective communication and negotiation between AI service providers and consumers. This framework not only facilitates the dynamic establishment of service terms and pricing but also promotes the integration of emerging open-source LLMs, advocating for a liberated and uncensored AI service ecosystem. The platform supports a variety of open-source models, such as LLaMA, GPT-Neo, GPT-J, and BigScience’s BLOOM, encouraging unrestricted access and innovation akin to the evolution of Linux.

The trend towards community-driven models, now gaining acceptance for commercial use, underscores this approach. Additionally, the increasing formation of internal AI or ML teams within commercial entities and technology companies highlights the strategic importance of AI capabilities in driving innovation and competitive advantage. Market analysis predicts substantial growth in the LLM and AI agent market, driven by the widespread adoption of AI technologies across various sectors, including healthcare, finance, education, and entertainment.

Cortensor extends its functionality by enabling LLM inferencing nodes to offer memory services, supporting continuous conversations or the construction of complex, decentralized applications. These configurations and the associated data can be encoded into smart contracts and stored off-chain, allowing for cost-effective and flexible deployment of sophisticated AI applications.

In conclusion, Cortensor represents a significant advancement in AI service delivery, offering a decentralized alternative to traditional web2.0 services and setting a new standard for the future of AI model hosting and utilization. This interdisciplinary collaboration among prestigious institutions and innovative startups lays the foundation for a scalable, efficient, and secure decentralized AI inference platform that meets the growing and diverse needs of the global market.


# Value Proposition

Cortensor offers a decentralized AI inference platform that combines gamified quality control, dynamic node capability assessment, and flexible privacy options through a Layer 2/3 blockchain architecture. This results in a scalable, efficient, and reliable AI inference service addressing supply and demand challenges, while incentivizing participation and maintaining high-quality standards.

## Key Differentiators

### **1. Gamified Supply-Side Quality Control**

* **First Layer (Supply Building):** Nodes participate in periodic, randomized "games" answering questions on various topics, allowing continuous quality assessment and capability categorization. This ensures a high-quality, well-categorized supply of inference nodes.
* **Second Layer (Demand Matching):** Consumers subscribe to inference services, and tasks are matched to nodes based on their capabilities, effectively managing both supply and demand.

### **2. Dynamic Node Capability Assessment**

* The gamification process allows Cortensor to maintain an up-to-date understanding of each node's capabilities, enabling precise matching of tasks to nodes. This improves efficiency and performance compared to static classifications.

### **3. Balanced Supply and Demand Approach**

* Cortensor comprehensively addresses both supply and demand. The first layer builds a quality-controlled supply, while the second layer efficiently matches this supply to consumer demand.

### **4. Incentivized Participation**

* Gamification serves as a quality control mechanism and incentivizes node operators to continuously maintain and improve their performance, fostering a more engaged and competitive supply-side ecosystem.

### **5. Flexible Consumer Subscription Model**

* Consumers can subscribe to inference services based on specific needs, offering more flexibility than fixed-tier systems used by competitors.

### **6. Potential for Synthetic Data Generation**

* The gamification process generates valuable question-answer data for training and improving AI models, offering an additional value stream.

## Addressing Adaptation and Supply Problems

### **Gamification as a Solution**

* **Engagement and Community Building:** Increases engagement and fosters a sense of community among participants.
* **Quality Control:** Ensures continuous quality control and categorization of nodes, maintaining a high standard of service for consumers.
* **Incentives:** Rewards participants, creating a competitive environment similar to Bitcoin mining, incentivizing node operators to join and stay active.

## **Token Economics**

* **Token Incentives:**
  * **Base Rewards:** Tokens for basic network participation and liveness checks.
  * **Performance-Based Rewards:** Additional tokens for high performance in the gamified evaluation process and successful completion of inference tasks.
* **Staking Mechanism:** Allows node operators to stake tokens for participation in higher-value tasks, ensuring vested interest in network quality.
* **Dynamic Token Pricing:** Adjusts token rewards based on network demand and supply, ensuring tokens remain valuable and attractive for participants.


# Whitepaper


# Page 1: Introduction and Vision

### **Introduction**

Artificial Intelligence (AI) is rapidly transforming industries and societies by offering unprecedented capabilities for automation, decision-making, and data analysis. However, the centralization of AI resources, data, and computing power poses significant challenges to accessibility, transparency, and innovation. To address these challenges, Cortensor proposes a decentralized AI inference network that democratizes access to AI technologies, empowers communities, and fosters a robust ecosystem of AI-driven applications.

Cortensor is a decentralized, community-powered platform designed to provide scalable, secure, and efficient AI inference services. By leveraging blockchain technology, Cortensor ensures that AI resources are distributed across a global network of nodes, creating a decentralized infrastructure that is both resilient and inclusive. Our vision is to make advanced AI tools accessible to everyone, regardless of their technical or financial resources, by integrating open-source models and incentivizing participation through a native token economy.

### **Vision**

Cortensor aims to revolutionize the AI landscape by creating a decentralized network that offers:

* **Universal AI Accessibility:** A platform where AI inference services are available to all, with easy integration across Web2 and Web3 ecosystems through REST API and Web3 SDK support.
* **Incentivized Community Participation:** A network that rewards contributors for providing computational resources, validating tasks, and engaging with the community. By integrating a native token, $COR, Cortensor ensures that all participants are fairly compensated for their contributions.
* **Scalable AI Infrastructure:** A robust, scalable platform that can handle a wide range of AI tasks, from simple classifications to complex generative models, making it suitable for a variety of applications across different industries.
* **Open-Source AI Models:** Cortensor is committed to integrating open-source AI models, starting with Llama, and expanding to other models over time. This ensures that the platform remains flexible, adaptable, and aligned with the latest advancements in AI research.
* **Decentralized Governance:** Empowering the community to have a say in the platform's future development and direction through decentralized governance mechanisms.

### **Problem Statement**

The current AI ecosystem is dominated by a few large entities that control the majority of AI resources and data. This centralization leads to several issues:

* **Limited Accessibility:** Access to advanced AI models and computing power is often restricted to those who can afford expensive infrastructure, creating barriers for smaller players and innovators.
* **Lack of Transparency:** Centralized AI systems operate as "black boxes," making it difficult to understand or verify the processes behind AI decision-making.
* **Scalability Challenges:** Centralized infrastructures are often bottlenecks, limiting the scalability of AI applications and preventing widespread adoption.
* **Innovation Stifling:** The concentration of AI resources in the hands of a few entities stifles innovation and hinders the development of new, cutting-edge applications.

### **Cortensor's Solution**

Cortensor addresses these challenges by creating a decentralized AI inference network that:

* **Decentralizes AI Resources:** By distributing AI computation across a global network of nodes, Cortensor democratizes access to AI tools and ensures that no single entity controls the majority of resources.
* **Enhances Transparency:** Through the use of blockchain technology and decentralized validation mechanisms, Cortensor provides a transparent, verifiable, and secure AI infrastructure.
* **Promotes Scalability:** The decentralized nature of Cortensor allows the network to scale effortlessly as more nodes join, ensuring that AI services can meet growing demand without compromising performance.
* **Fosters Innovation:** By incentivizing community participation and supporting open-source models, Cortensor creates an environment where innovation can thrive, enabling the development of novel AI applications that benefit society at large.

### **Conclusion**

Cortensor represents the next evolution in AI infrastructure, bringing together the power of decentralization, open-source collaboration, and community-driven innovation. By addressing the limitations of centralized AI systems, Cortensor paves the way for a future where AI is accessible, transparent, and scalable for all.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Page 2: Architecture and Technical Overview

Cortensor is built on a multi-layered architecture designed to ensure scalability, security, and efficient AI inference across a decentralized network. This section provides an overview of the key components of the Cortensor platform and the technologies that drive its functionality.

### **Core Components**

1. **Multi-Layer Blockchain Architecture**
   * **Layer 1 (L1): Registration and Onboarding**
     * **Technology:** Ethereum or Layer 2 solutions like Arbitrum, Base, or Optimism.
     * **Purpose:** This layer handles the secure registration and onboarding of miners and users, forming the foundation of the Cortensor network. It ensures that all participants are verified and trusted, laying the groundwork for a secure and reliable network.
   * **Layer 2 (L2): Health and Capability Verification**
     * **Technology:** Layer 2 chains optimized for scalability and speed.
     * **Purpose:** This layer monitors the health and capabilities of nodes through Proof of Inference (PoI) and Proof of Useful Work (PoUW) mechanisms. It ensures that all nodes meet the required standards for participation and that the network remains robust and reliable.
   * **Layer 3 (L3): User Interaction and Service Layer**
     * **Technology:** Layer 2 or Layer 3 chains tailored for dApp interactions and user services.
     * **Purpose:** This layer facilitates interactions between users and the Cortensor network, allowing them to access AI inference services and other functionalities. It is the primary interface for users to interact with Cortensor’s decentralized AI capabilities.
2. **Proof of Inference (PoI) and Proof of Useful Work (PoUW)**
   * **Proof of Inference (PoI):** Ensures that AI inference tasks are performed correctly and consistently across different nodes using the same model. This mechanism validates the accuracy of the inference results by comparing outputs from multiple nodes and ensuring they match within an acceptable range.
   * **Proof of Useful Work (PoUW):** Goes beyond simple validation by ensuring that the work performed by nodes is not only correct but also useful and relevant. For example, nodes might generate synthetic data or validate the outputs of AI models by cross-referencing with other nodes. This process ensures that the network’s resources are used effectively and that the outputs generated are meaningful.
3. **Node Lifecycle and Task Assignment**
   * **Node Activation:** When a node joins the network, it signals its readiness by activating itself. The network then assigns tasks to the node, such as PoI and PoUW tasks, to verify its capabilities and ensure it meets the network’s standards.
   * **Task Execution:** Nodes are tasked with creating virtual blocks or transactions, generating detailed prompts based on agreed topics, and providing inference results. These tasks are assigned based on the node's capabilities and performance, with more complex tasks reserved for higher-performing nodes.
   * **Ephemeral Nodes:** Once a node has successfully completed a series of tasks, it enters an "ephemeral" state, where it can serve user requests for a limited time. These nodes can be reserved or public, depending on the user’s requirements for privacy, performance, and other factors.
   * **User Sessions and Resource Allocation:** Users create sessions by depositing tokens, which are used to allocate network resources for AI inference tasks. The network uses these sessions to plan capacity and ensure that nodes are available to meet user demands.
4. **Quantization and Model Support**
   * **LLM Quantization:** Cortensor utilizes quantization to support a wide range of hardware, from low-end CPUs to high-end GPUs. Quantization reduces the precision of the models, allowing them to run on less powerful hardware without sacrificing too much performance. This approach ensures that Cortensor can accommodate a broad spectrum of devices, making AI inference more accessible and cost-effective.
   * **Model Flexibility:** Initially, Cortensor supports quantized models, particularly for tasks that do not require high precision. Over time, the platform will expand to support higher bit quantization and non-quantized models, enabling more complex and resource-intensive AI tasks.
5. **Data Management and Privacy**
   * **Off-Chain Data Storage:** Cortensor uses decentralized storage solutions like IPFS to manage large volumes of data off-chain. This approach reduces the cost of operation and ensures that data remains accessible and secure.
   * **Data Encryption:** All data transmitted between nodes is encrypted, ensuring privacy and security. Users can choose to use public or private nodes depending on their privacy requirements, with the option to select higher-security nodes for sensitive tasks.

### **Conclusion**

Cortensor’s architecture is designed to provide a flexible, scalable, and secure platform for decentralized AI inference. By leveraging a multi-layered blockchain structure, innovative proof mechanisms, and advanced quantization techniques, Cortensor ensures that AI resources are accessible to all, regardless of their hardware capabilities. This architecture not only supports the current needs of AI inference but also lays the foundation for future advancements in decentralized AI technologies.

Reference: <https://docs.cortensor.network/technical-architecture>

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Page 3: Incentive Structure and Tokenomics

Cortensor’s incentive structure and tokenomics are meticulously designed to build a robust and sustainable decentralized AI ecosystem. This system ensures that all participants—whether they are node operators, validators, or regular users—are fairly rewarded for their contributions, while also maintaining the network's long-term success and scalability. The structure is built around the $COR token, which serves both as a utility and governance token within the Cortensor network.

### **Overview**

The incentive structure is critical to ensuring the smooth operation and growth of the Cortensor network. Participants are rewarded with $COR tokens, which are used for various purposes, including staking, network security, and governance. These rewards are distributed based on performance, reliability, and the overall contribution to the network's growth.

### **Key Incentive Mechanisms**

**1. Token-Based Rewards**

Cortensor uses its native token, $COR, to incentivize a range of activities within the network:

* **Basic Network Participation:**
  * **Liveness and Health Checks:** Nodes earn $COR tokens for performing basic network liveness and health checks, which ensure the network's stability and reliability.
* **AI Inference Tasks:**
  * **User Requests:** Nodes receive additional $COR tokens for executing AI inference tasks requested by users. The complexity and resource requirements of these tasks determine the scale of the rewards.
* **Validation and Verification:**
  * **Guard/Validation Nodes:** These nodes earn $COR tokens by validating and scoring inference results, ensuring the accuracy and reliability of the network's outputs.

**2. Multi-Level Validation System**

Cortensor employs a thorough multi-level validation process to ensure high-quality outputs:

* **Router Nodes:**
  * **Task Assignment and Initial Validation:** Router nodes are responsible for assigning tasks to appropriate inference nodes and performing the initial validation of results. They earn rewards based on the efficiency and accuracy of these tasks.
* **Guard/Validation Nodes:**
  * **Detailed Validation:** These nodes conduct in-depth checks and validate the results generated by inference nodes. They score outputs for accuracy and reliability, and rewards are tied to the quality of their validations.

**3. Staking and Slashing**

Staking is an integral part of Cortensor’s incentive structure, providing security and additional rewards:

* **Staking for Participation:**
  * **Node Operators:** Node operators must stake $COR tokens as a security deposit to participate in the network, ensuring their commitment to maintaining network standards and reliability.
* **Staking for Rewards:**
  * **Regular Users:** Users can stake $COR tokens to earn APR (Annual Percentage Rate) rewards, which contributes to network security and reduces token sell pressure.
* **Slashing for Misbehavior:**
  * **Penalties:** Nodes that fail to meet network standards or engage in malicious behavior may have a portion of their staked tokens forfeited, ensuring accountability and encouraging high standards.

**4. Gamified Supply-Side Development**

Cortensor employs a gamified approach to building and maintaining a quality supply of inference nodes:

* **Level 1: Liveness Checks:**
  * **Network Operations:** Nodes engage in basic network operations, earning rewards for maintaining consistent availability and responsiveness.
* **Level 2: Capability Assessment:**
  * **Performance Evaluation:** This level measures each node’s speed, accuracy, and capabilities, with higher-performing nodes qualifying for more complex tasks and higher rewards.
* **Competitive Environment:** The gamified system fosters competition among node operators, encouraging continuous improvement of hardware and performance. This ensures a diverse and capable network of inference nodes.

### **AI Marketplace Incentives**

Cortensor’s decentralized AI marketplace provides additional earning opportunities for node operators:

* **Marketplace Participation:**
  * **Specialized AI Models and Services:** Node operators can offer specialized AI models or services through the marketplace, earning additional $COR tokens. Smart contracts govern these transactions, ensuring fair compensation.
* **Incentive Alignment:** The marketplace encourages innovation and sharing within the ecosystem, benefiting developers and users alike by providing a diverse range of tools and services.

### **User Payments and Additional Incentives**

Nodes can also earn from direct user payments in addition to network-based rewards:

* **User Payments:**
  * **Deposits for Services:** Users deposit $COR tokens to utilize the network's AI inference services, ensuring predictable revenue for node operators and helping with capacity planning.
* **Dual Reward System:** Nodes earn from both network incentives (via PoI and PoUW) and direct user payments, creating a dynamic and sustainable reward structure.

## **Tokenomics**

### **Token Utility:**

* **$COR Token:** The native token of the Cortensor ecosystem, $COR, serves as both a utility and governance token. It is used to reward node operators, validators, and participants in various network activities, ensuring active participation and high-quality contributions.
* **Staking:** $COR tokens can be staked by node operators as a security deposit, ensuring their commitment to maintaining network reliability. Regular users can also stake $COR tokens to earn APR, contributing to network security and reducing sell pressure.
* **Governance:** Token holders can participate in governance decisions, shaping the future direction of the Cortensor platform.

### **Token Distribution:**

* **Network Incentives:** A significant portion of $COR tokens is allocated for network incentives, rewarding nodes for performing tasks such as Proof of Inference (PoI) and Proof of Useful Work (PoUW). These rewards ensure that the network remains robust and reliable.
* **User Payments:** Users pay for AI services in $COR tokens. This payment structure provides a direct incentive for node operators to maintain high performance, as they are compensated for fulfilling user requests.
* **Staking Rewards:** In addition to earning tokens through network participation, staking $COR tokens also offers users and node operators a way to earn additional rewards. Staking helps secure the network and incentivizes long-term commitment.

### **Future Developments**

Cortensor is committed to refining its incentive and tokenomics structure based on ongoing network performance and community feedback:

* **Dynamic Reward Adjustments:**
  * **Real-Time Adaptation:** Rewards may be adjusted in real-time based on network demand and resource availability, ensuring that the incentive structure remains effective and sustainable.
* **Specialized Incentives:** Additional rewards may be introduced for niche AI tasks or industry-specific applications, further expanding the network's utility.
* **Integration with DeFi Protocols:** To provide additional yield opportunities, Cortensor plans to integrate $COR tokens with decentralized finance (DeFi) protocols.

### **Summary**

Cortensor’s incentive and tokenomics structure is designed to create a thriving and sustainable decentralized AI ecosystem. By aligning incentives across all participants—whether through network participation, staking, or contributing to the AI marketplace—Cortensor ensures continuous improvement, high-quality contributions, and long-term commitment to the platform’s growth and success. As the network evolves, the incentive structure will adapt to maintain its effectiveness and relevance.

Reference: <https://docs.cortensor.network/community-and-ecosystem/incentives-and-reward-system>

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Page4: Development Roadmap and Phases

Cortensor's journey towards creating a decentralized AI inference platform is ambitious yet achievable with community support. This roadmap outlines the key milestones, focusing on both technical and community development phases from Q3 2024 through 2025. While the timeline is carefully planned, it remains flexible to accommodate adjustments based on real-time feedback and evolving needs.

### **Q3 2024: Launch and Genesis**

**Objective:** Officially launch Cortensor and initiate the genesis phase, establishing the technical foundations and engaging the early community.

**Key Activities:**

* **Staking dApp:** Launch the staking dApp for $COR tokens, allowing early community supporters to participate in staking and become early contributors.
* **Genesis Phase:** Invite the community to stake tokens and prepare for the upcoming alpha testing.
* **Community Building:** Offer incentives for early participation and build a strong foundation of supporters.

**Timeline:**

* **July-September 2024:** Deploy staking dApp, initiate the genesis phase, and engage with early community members.

### **Q4 2024: Closed Alpha Testing**

**Objective:** Begin closed alpha testing focused on the mining portion (Layer 1) of the Cortensor network, laying the groundwork for technical validation.

**Key Activities:**

* **Alpha Testing:** Engage select community members as alpha testers to test node functionality, focusing on network tasks to prove quality and capacity in Generative AI (GenAI) inferencing, particularly with LLMs.
* **Compatibility Assessment:** Assess compatibility across various hardware setups (CPUs, GPUs, etc.).
* **Development Refinement:** Conduct internal development to refine the existing dev version and prepare it for alpha testing.

**Timeline:**

* **October-November 2024:** Finalize development to reach closed alpha readiness.
* **December 2024:** Polish the platform and resolve any critical issues identified during internal testing.

### **Q1 2025: Open Alpha Launch**

**Objective:** Expand testing to a broader audience with an open alpha phase, continuing technical validation and strengthening network robustness.

**Key Activities:**

* **Open Alpha:** Launch open alpha, allowing more participants to test the mining features and start earning points.
* **Feedback Collection:** Gather feedback on network performance, task distribution, and node reliability.
* **Airdrop Planning:** Plan for airdrops based on participation and contribution during the open alpha.

**Timeline:**

* **January-February 2025:** Initiate open alpha, monitor performance, and collect data.
* **March 2025:** Analyze feedback, make necessary adjustments, and prepare for the next phase.

### **Q2 2025: User Request Testing Phase (Layer 2)**

**Objective:** Begin testing the user request serving portion of the platform (Layer 2), focusing on the technical aspects of user interaction and task execution.

**Key Activities:**

* **Layer 2 Testing:** Introduce Layer 2 testing, focusing on handling real-time user requests and AI inference tasks.
* **Scalability Testing:** Continue refining the network's ability to process and respond to user queries efficiently.
* **Airdrop Incentives:** Include airdrop incentives for users who participate in testing and provide valuable feedback.

**Timeline:**

* **April-May 2025:** Launch the user request testing phase, focusing on scalability and performance.
* **June 2025:** Address any challenges, optimize the system, and prepare for broader rollouts.

### **Q3 2025: Full User Request and Mining Integration**

**Objective:** Fully integrate and finalize both Layer 1 (Mining) and Layer 2 (User Request) functionalities, solidifying the technical infrastructure.

**Key Activities:**

* **Integration:** Combine learnings from the previous phases to optimize the network for broader usage.
* **Final Testing:** Conduct final rounds of testing and refinements across both layers.
* **Airdrop Distribution:** Finalize airdrop strategies and distribute rewards to participants from the previous phases.

**Timeline:**

* **July-August 2025:** Integrate Layer 1 and Layer 2, ensuring seamless operation between mining and user request functionalities.
* **September 2025:** Prepare for the official launch of the fully integrated system, targeting broader adoption and use.

### **Q4 2025 and Beyond: Testnet and Mainnet Launch**

**Objective:** Transition from alpha testing to testnet, leading to the mainnet launch, marking the completion of Cortensor's technical roadmap.

**Key Activities:**

* **Testnet Launch:** Launch the testnet to simulate real-world conditions and further validate the network's capabilities.
* **Performance Testing:** Perform extensive testing to identify and resolve any remaining issues.
* **Mainnet Preparation:** Prepare for the mainnet launch, focusing on security, scalability, and performance.

**Timeline:**

* **October-November 2025:** Deploy the testnet to gather final performance data.
* **December 2025:** Transition from testnet to mainnet, opening the Cortensor network to the public with full functionality.

### **Summary**

This comprehensive roadmap provides a clear vision for Cortensor’s development, focusing on both technical milestones and community engagement. From the initial launch and closed alpha testing to the eventual mainnet deployment, each phase is designed to ensure that the Cortensor platform is stable, secure, and scalable. Adjustments may be made as we progress, ensuring that Cortensor is ready for broader adoption in the decentralized AI ecosystem.

Reference: <https://docs.cortensor.network/roadmap>

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Page5: Summary

### **Cortensor: A Decentralized AI Inference Platform**

#### **Introduction**

Cortensor is pioneering the future of AI by developing a decentralized, community-driven AI inference platform. Built on a robust multi-layered blockchain architecture, Cortensor integrates advanced AI capabilities with blockchain technology, providing scalable and reliable AI services. This platform is designed to democratize AI, making it accessible to everyone, from individuals to enterprises, while ensuring high-quality performance and innovation.

### **Core Features**

1. **Decentralized AI Inference:**
   * Cortensor enables decentralized AI inference by leveraging community-operated nodes.
   * Nodes perform AI tasks, contributing to the network's overall computational power.
   * The platform supports a wide range of hardware, ensuring inclusivity and broad participation.
2. **Quantization for Inclusivity:**
   * Cortensor uses LLM quantization to adapt AI models for various hardware types, from low-end CPUs to high-end GPUs.
   * Quantization allows more devices to participate, expanding the network's capabilities while maintaining cost efficiency.
   * Users can choose between quantized and non-quantized models based on their accuracy and performance needs.
3. **Proof of Inference (PoI) and Proof of Useful Work (PoUW):**
   * These unique consensus mechanisms ensure the accuracy and usefulness of AI inference results.
   * PoI validates that nodes perform tasks correctly, while PoUW assesses the practical value of the output.
   * These processes are essential for maintaining the integrity and reliability of the network.
4. **Incentive Structure:**
   * Cortensor's incentive system rewards nodes for contributing to the network, including tasks related to PoI, PoUW, and user requests.
   * Nodes earn $COR tokens through basic participation, task execution, and staking.
   * The platform encourages continuous improvement and high-quality contributions, with rewards scaling based on task complexity and node performance.

### **Development Roadmap**

Cortensor’s development is structured across several key phases, each with specific goals and milestones:

1. **Q3 2024: Launch and Genesis**
   * Begin staking for $COR tokens and engage the community.
   * Prepare for the closed alpha phase, focusing on mining and network validation.
2. **Q4 2024: Closed Alpha Testing**
   * Test core functionalities with selected community members.
   * Focus on AI inference tasks, hardware compatibility, and network stability.
3. **Q1 2025: Open Alpha Launch**
   * Expand testing to a broader audience.
   * Collect feedback and refine the platform for wider use.
4. **Q2 2025: User Request Testing (Layer 2)**
   * Test user-facing functionalities and real-time task processing.
   * Offer incentives for participation and gather data for optimization.
5. **Q3 2025: Full Integration**
   * Combine mining and user request functionalities for seamless operation.
   * Finalize airdrop strategies and reward early participants.
6. **Q4 2025 and Beyond: Testnet and Mainnet Launch**
   * Transition from testing phases to a fully operational mainnet.
   * Focus on security, scalability, and real-world application.

### **Community and Ecosystem**

Cortensor’s success hinges on the active participation and engagement of its community. The platform fosters an environment where contributors can collaborate, innovate, and earn rewards through various roles, including model development, validation, and governance participation. As the network evolves, Cortensor aims to establish a vibrant ecosystem of AI services, dApps, and enterprise solutions, with decentralized governance at its core.

### **Conclusion**

Cortensor is not just another AI platform; it represents a paradigm shift in how AI is developed, deployed, and accessed. By combining the power of decentralized networks with cutting-edge AI technologies, Cortensor is paving the way for a more inclusive, efficient, and innovative future in AI. The journey is ambitious, but with the support of a dedicated community and a clear, structured roadmap, Cortensor is well-positioned to become a leader in decentralized AI inference.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Pitch Memo

version 0

## Cortensor: Decentralized AI Execution & Verification Layer

### Overview

Cortensor is a decentralized AI execution and verification layer designed to democratize access to powerful AI systems while ensuring transparency, efficiency, and trust. It reimagines how AI workloads are distributed, executed, and validated across a permissionless global network of compute nodes, powered by a native incentive and governance system.

### Problem

Today, AI is gated by centralized infrastructure monopolies, opaque model execution, and trust assumptions that inhibit its integration with public systems like blockchains. AI services are vulnerable to hallucinations, unverifiable outputs, and exclusive access models.

### Solution

Cortensor solves this by building a decentralized network for AI inferencing, synthetic data generation, and model execution. The network includes validation mechanisms such as Proof of Inference (PoI) and Proof of Useful Work (PoUW) to ensure correctness and incentivize performance.

### Key Differentiators

* Model-Agnostic Execution: Any LLM or generative model (e.g., LLaMA 3, Mistral, Stable Diffusion) can be deployed by the community.
* PoI & PoUW SLAs: Built-in mechanisms for inference verification, uptime guarantees, and performance-based rewards.
* Validation Layer: Statistical sampling, redundancy checks, and multi-node confirmation ensure correctness and trust.
* Network-Generated Tasks: The system supports internal jobs to stimulate activity and bootstrap node engagement. These tasks are gamified to continuously assess node quality through randomized question-answer challenges, promoting active participation. This approach ensures continuous quality control, enhances dynamic node classification, and drives community engagement. The QA data produced can also be reused for training AI models, adding an additional layer of value creation.
* Synthetic Data Generation: Miner nodes can generate synthetic datasets for ML applications.
* Incentive System: Native token economy incentivizes compute contributions and validator behavior.
* Web2 & Web3 Integration: Works with traditional APIs and smart contracts for trustless AI access.
* Light & Heavy Nodes: Supports diverse hardware, from CPUs to GPUs, via quantization and job matching.
* AI Oracle Functionality: Allows smart contracts to query LLMs through decentralized middleware.
* On-chain Billing: Supports deposits in COR or ETH and token payments through smart contracts.

### Use Cases

* AI inference for Web2 & Web3 apps
* Synthetic data generation for ML training
* LLM-based oracles for smart contracts
* AI agent marketplaces & decentralized assistants
* Trustless, verifiable AI output pipelines

### GTM & Adoption Strategy

* Closed Alpha Testing: Incentivized devnets & testnets with leaderboard-based rewards (e.g., Phase #3, #4, #5, #6 and beyond). These early stages help build a resilient developer and node operator community. Cortensor’s current testnet spans \~200 organic nodes validating the early demand and value of the platform.
* Token Incentives: Mineable token model with controlled sell pressure and staking pools. COR is essential to the ecosystem as it functions like 'gas' for inference - used in every AI task. Utility scales with real usage: more app traffic → more COR demand.
* Developer SDKs & APIs: Cortensor is built with a developer-first mindset, offering intuitive SDKs and APIs for both Web2 and Web3 builders. Our strategy emphasizes organic adoption through:
* Sample & Demo Apps: Real-world examples to showcase Cortensor's capabilities and inspire developers.
* Hackathons: Developer-focused events where participants build on Cortensor, submit projects, and win prizes. These serve as our primary GTM channel to:
  * Drive hands-on adoption
  * Gather direct feedback on integration and performance
  * Promote community-driven innovation
* Community Engagement: Outreach through dev forums, open-source contributions, and Discord/Twitter communities.
* No Traditional Sales: Inspired by Stripe, Twilio, OpenAI, and Alchemy, we prioritize product-led growth - letting the platform prove itself.
* Growth Blueprint:
  * Build a killer platform
  * Empower developers to launch with minimal friction
  * Enable organic use case growth across sectors
  * Scale BD, GTM, and ecosystem support once traction is proven This lean, scalable approach ensures Cortensor grows where it matters most—at the hands of its builders.
* Strategic Partnerships: Align with decentralized infrastructure providers (e.g., Aethir, Stratos, Filecoin) to extend compute and storage capacity.

#### This GTM strategy aligns tightly with COR’s token utility model:

* Every inference request consumes COR.
* Cost per request depends on: token usage, inference complexity, and current COR market value.
* Pricing may be pegged to stable benchmarks (e.g., USD per 1k tokens), but converted dynamically to COR.
* Developer-facing staking models are under exploration - e.g., teams stake COR to host AI apps, gaining usage credits and incentives to stay long-term.
* Over time, this creates a sustainable flywheel: developers build → apps grow → usage increases → COR demand rises.

### Key Components

* Router Nodes: Handle user requests, route them to available miner nodes, and optimize load balancing and model selection.
* Miner Nodes: Perform AI inference jobs (e.g., LLaMA models), including quantized versions for low-end devices.
* Oracle/Master Nodes: Validate miner outputs, sample responses, and ensure consensus in PoI systems.
* Client Nodes: Enable users and developers to submit requests, monitor tasks, and access results.

### Architecture & Infrastructure

* Job Scheduling & Coordination: Smart contract-based hub for session creation, worker selection, and result submission
* Validation & Sampling: Validator nodes use statistical sampling to check miner output correctness
* Storage & Data Management: Uses IPFS and plans to expand to Filecoin and Stratos for off-chain file storage
* Security & Privacy: ECDSA encryption for confidential data passing and selective on-chain/off-chain exposure. Trusted Execution Environments (TEEs) will also be considered to enhance secure execution of sensitive workloads.

### Business Model

* Tokenomics: 1B total supply, 40% initial DEX allocation, vesting for team, staking with ETH revenue sharing
* Revenue: COR & ETH paid by users for inference and other services, split between validators, miners, and treasury

### How to Think About Cortensor

* Uber for AI (Everyone): Cortensor is like Uber for AI - providing on-demand AI inference without the need to own or manage GPUs. Miners contribute compute power, while users access scalable, decentralized AI services. Think of it as OpenAI, but without centralized infrastructure or model ownership.
* Tesla Simulation for Synthetic Data (AI Practitioners): For AI scientists, Cortensor functions like Tesla's simulation engine. Just as Tesla generates synthetic driving data to train its models, Cortensor enables the creation of synthetic datasets that are scalable, diverse, and ideal for improving AI performance beyond real-world limitations.
* Stripe for AI (Developers): Cortensor is to AI what Stripe is to payments. It simplifies AI integration for developers through intuitive SDKs - whether you're building in Web2 or Web3. Just like adding a payment button, developers can embed LLM functionality with just a few lines of code.

### Vision

Cortensor is building the execution layer for a decentralized AI future where inference is trustless, verifiable, universally accessible, and composable. In a world dominated by opaque, centralized AI gatekeepers, Cortensor stands for openness, composability, and proof-based intelligence.

Contact\
Website:[ Cortensor.network<br>](https://cortensor.ai/)Twitter:[ @CortensorAI<br>](https://twitter.com/CortensorAI)Dashboard: [https://dashboard-alpha.cortensor.network<br>](https://dashboard-alpha.cortensor.network)GitHub:[ github.com/Cortensor<br>](https://github.com/Cortensor)Medium: [medium.com/@cortensor<br>](http://medium.com/@cortensor)Email: <info@cortensor.net>\
Draft: <https://docs.google.com/document/d/1TqAuV1CPR2zfFK5bkk3G5vr01hz6qc9r_kUsqew8kYU/edit?tab=t.0><br>

\ <br>

<br>


# Introduction

Cortensor is a pioneering decentralized AI inference and development platform designed to democratize AI by utilizing decentralized networks and open-source models. This platform aims to overcome the limitations of centralized AI services, offering a scalable and cost-effective solution for AI inference and development.

In this section, you will find an overview of Cortensor's key features, including decentralized AI inference, blockchain integration, and the use of open-source models. Additionally, you will be introduced to the core concepts and technical details that form the foundation of Cortensor, as well as the community and ecosystem that support its development and growth.

Explore further to understand how Cortensor is transforming the AI landscape by enabling efficient, transparent, and accessible AI technology.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# What is Cortensor?

Cortensor is a cutting-edge decentralized AI inference and development platform. It is designed to democratize access to artificial intelligence by leveraging the power of decentralized networks and open-source models. By moving away from centralized AI services, Cortensor aims to provide a scalable, cost-effective, and efficient solution for AI inference and development.

## **Key Characteristics**

* Decentralized AI Inference: Cortensor utilizes a network of distributed computing resources to perform AI tasks, enhancing efficiency and scalability while reducing reliance on large, centralized data centers.
* Open-Source Models: The platform supports a variety of open-source AI models, allowing for flexible and unrestricted AI applications. Users can fine-tune and deploy these models to suit their specific needs.
* Blockchain Integration: Cortensor integrates blockchain technology to ensure secure, transparent transactions and incentivized collaborations within the network. This promotes trust and innovation across the community.
* Community-Driven Development: Cortensor encourages contributions from its community, fostering an ecosystem where innovation is rewarded, and diverse AI solutions can thrive.

## **Objectives**

* Democratize AI: Making AI technology accessible to a broader audience by reducing barriers to entry.
* Promote Innovation: Encouraging the development of new AI models and applications through a fair and incentivized marketplace.
* Enhance Efficiency: Optimizing resource usage and reducing operational costs associated with AI development and inference.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Key Features & Benefits

## **Key Features**

1. Decentralized AI Inference
   * Distributed Computing Power: Utilizes a global network of computing resources, ensuring efficient and scalable AI processing.
   * Reduced Reliance on Centralized Data Centers: Minimizes the dependency on large, centralized infrastructure, leading to more resilient and flexible AI operations.
   * NOTE: add Intelligent Routing System
2. Open-Source Models
   * Flexible Model Integration: Supports a wide array of open-source AI models, allowing for customization and fine-tuning to meet specific application needs.
   * Unrestricted Access: Provides access to powerful AI models without the limitations and censorship of proprietary systems.
3. Blockchain Integration
   * Secure Transactions: Ensures the security and transparency of transactions within the platform through blockchain technology.
   * Incentivized Collaborations: Promotes a fair and transparent marketplace where contributions and innovations are rewarded.
4. Scalability and Efficiency
   * Optimized Resource Usage: Efficiently allocates computing tasks across the network, reducing operational costs and enhancing performance.
   * Cost-Effective Solutions: Offers a scalable AI infrastructure that grows with the needs of users, providing a cost-effective alternative to traditional AI services.
5. Community-Driven Development
   * Inclusive Ecosystem: Encourages contributions from a diverse community of developers and researchers, fostering innovation and collaboration.
   * Reward Mechanisms: Implements incentive structures to reward valuable contributions, ensuring continuous improvement and development.

## **Benefits**

1. Accessibility
   * Democratized AI: Lowers the barriers to entry for AI development and usage, making advanced AI technologies accessible to a broader audience.
   * Global Participation: Enables participation from a global community, leveraging diverse perspectives and expertise.
2. Innovation
   * Rapid Development: Facilitates the rapid development and deployment of new AI models and applications.
   * Collaborative Environment: Fosters a collaborative environment where ideas can be shared and developed collectively.
3. Cost Efficiency
   * Reduced Costs: Significantly lowers the costs associated with AI inference and development compared to traditional centralized solutions.
   * Efficient Use of Resources: Ensures efficient use of computing resources, maximizing the return on investment.
4. Transparency and Security
   * Blockchain Security: Leverages blockchain technology to provide secure and transparent operations.
   * Trustworthy Transactions: Ensures all transactions and collaborations are transparent and verifiable, building trust within the community.
5. Scalability
   * Flexible Scaling: Easily scales with the growth of AI projects, accommodating increasing computational needs without compromising performance.
   * Adaptive Infrastructure: Adapts to the evolving needs of users, providing a robust platform for long-term AI development.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Vision & Mission

### **Vision**

At Cortensor, our vision is to democratize artificial intelligence through a decentralized, community-powered network of inferencing nodes and infrastructure. We aim to provide the critical last mile of AI delivery and integration, ensuring universal access to advanced AI tools and capabilities.

We are building a robust AI inferencing infrastructure by utilizing a network of community and commodity hardware, balancing workloads across low and high-end devices. This approach optimizes resource utilization, making AI accessible for everyday applications without relying solely on specialized or high-end GPUs. By leveraging community and commodity hardware, Cortensor ensures that AI is more cost-effective and accessible to everyone, every day.

Additionally, we leverage open-source models to enhance accessibility and foster a collaborative innovation environment. Our long-term vision includes expanding beyond AI inferencing to encompass synthetic data generation and generalized task and job management. Furthermore, we will develop L2/L3 blockchain for AI inferencing data and related data hosting, such as embeddings or data sources needed for AI agents, while ensuring communities are properly incentivized and share in the revenue. Future AI agents will utilize the blockchain to orchestrate processes and create a marketplace for AI agents with proper incentivization.

We plan to expand into areas such as fine-tuning open-source data models with watermarks and creating a marketplace to monetize models developed by the community, driving further innovation and providing additional revenue streams for contributors.

Cortensor envisions a future where AI is seamlessly integrated into every aspect of daily life, powered by a decentralized network that fosters innovation, inclusivity, and shared success. Through community collaboration and equitable access, we aim to revolutionize AI technology and its applications, paving the way for a smarter, more connected world. We aim to create an open-source platform with the functionality of industry leaders like OpenAI and Huggingface, but in a decentralized manner that is powered and governed by the community, accelerating AI innovation and driving rapid development through incentivized contributions.

***

### **Mission**

At Cortensor, our mission is to build a decentralized AI infrastructure and network democratically, ensuring that advanced AI technology is accessible and cost-effective for everyone. We emphasize community collaboration, open-source models, and inclusivity, bringing together AI professionals and practitioners with proper incentivization to foster innovation and advancement. Cortensor aims to be the decentralized, community-powered alternative to traditional AI platforms, leveraging blockchain technology to drive progress and make AI a universally available resource. Through this approach, we aspire to revolutionize AI delivery, making it an integral part of everyday life while promoting equitable access and shared success.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Copy of Team & Contributors

Cortensor was founded by a group of experienced engineers and entrepreneurs with deep expertise in distributed systems, blockchain infrastructure, and AI platforms. While the project was initiated by a core team, Cortensor is developed through decentralized, community-driven collaboration with contributors from around the world.

### Our Background

The founding team & contributors have:

* Successfully exited two traditional VC-backed startups
  * One acquired by a multinational trillion-dollar internet/software company
  * Another acquired by a fintech unicorn
* Led enterprise blockchain and DePIN projects, with a focus on decentralized networking and data infrastructure
* Built and scaled large distributed systems from concept to production, leveraging ledger and blockchain technologies

This experience laid the groundwork for Cortensor’s core principles: scalable, verifiable, and decentralized AI infrastructure, built in the open and shaped by a global community.

#### What Cortensor builds - <https://x.com/CryptoRyuma/status/1920280892238672256>

***

### Engineering

The lead architect graduated from the University of Southern California (USC) in Computer Science in 2011 and joined Google through a $100M acquisition. Over the last decade, he has contributed to major infrastructure projects in gaming, mobile OS, cloud computing, blockchain, and fintech.

**Previous Roles and Achievements:**

* Co-founded a DePIN startup acquired in 2020 by a Silicon Valley fintech unicorn
* Led backend infrastructure for games with over 100 million users
* Contributed to key Google projects, including Chrome Mobile, Android OS, and Google Cloud

He now helps to lead architectural efforts within Cortensor—working alongside the broader community—to build a decentralized, verifiable AI network based on Proof-of-Inference and open infrastructure. The project prioritizes trust, transparency, and global collaboration over centralized control.

* <https://www.linkedin.com/in/jonghyeopkim>

### Operation

Shelby has a background in IT with a bachelor-level degree and is now full-time in trading and crypto operations. Known for a high standard of quality and integrity, Shelby has worked as a trusted mod in a few carefully selected projects, always prioritizing transparency and long-term value.

A core contributor to Cortensor since the early days, Shelby plays a key role in community management across Telegram, Discord, and X, while also supporting internal coordination, operational planning, and node operator onboarding.

From organizing daily workflows to helping streamline support and validator processes, Shelby brings consistency and clarity to Cortensor’s decentralized operations.

Telegram: [shelby\_xb](https://t.me/shelby_xb)\
X: [cryptdshelby](https://x.com/cryptdshelby)

### Operation

Kim is an Information Systems student with hands-on experience in Web3 community management. As a core contributor at Cortensor, Kim helps lead community moderation, internal coordination, and operational support in a fast-moving, decentralized environment.

With a focus on communication and relationship-building, Kim actively engages global communities across Telegram, Discord, and X, helping maintain a welcoming, well-informed space for users and contributors alike.

Curious, consistent, and mission-driven, Kim continues to grow with the ecosystem while supporting meaningful collaboration across teams.

Telegram: [Kimhan777](https://t.me/Kimhan777)\
X: [0xkimhan](https://x.com/0xkimhan)

***

### Infrastructure & DevOps - Agnc

Agnc entered the crypto space in 2015, starting as a miner, node operator, and airdrop hunter. By 2019, he shifted focus toward technical infrastructure, bringing a background in technical sales and system administration to Web3 operations.

As one of the early Cortensor node operators, Agnc helps run and maintain the Cortensor RPC infrastructure, supporting node onboarding and validator uptime. He brings hands-on expertise in server setup, system monitoring, and infra maintenance, with a strong emphasis on reliability and clarity.

Agnc continues to support the Cortensor network’s infrastructure backbone, contributing to smooth operations across testnet and DevNet environments.\
\
Telegram: [centertopup](https://t.me/centertopup)\
X: [01\_choose](https://x.com/01_choose)

### Infrastructure & DevOps - RayRedd

In crypto since 2012, RayRedd began as an early miner and airdrop hunter. In 2024, he shifted focus to validator infrastructure, combining his DevOps background with a passion for onboarding new node operators through his Telegram channel.

He brings hands-on experience in server ops, monitoring, and network maintenance, and actively validates on: Cortensor, Aztec, CrossFi, Symphony, Empeiria, Airchains, Warden, and Humanode.

At Cortensor, he supports validator operations, node onboarding, and infrastructure coordination.

Telegram: [CryptoNodeRedd](https://t.me/CryptoNodeRedd) \
X: [0xRedd ](https://x.com/0xRedd)\
Discord: @rayredd

### Infrastructure & Tooling - Scerb

Scerb is an engineer and CTO of an R\&D company, with multiple granted patents in his field. With a long-standing interest in crypto and AI, he brings a forward-looking mindset and technical depth to decentralized infrastructure.

As a contributor to Cortensor, Scerb operates and maintains RPC infrastructure, builds tooling and watchdog systems, and supports node operators across environments. His work helps ensure network reliability and performance as the system scales.

Combining real-world engineering expertise with a passion for emerging tech, Scerb continues to expand Cortensor’s operational backbone with precision and care.

Telegram: Bo\
X: [Will429910](https://x.com/Will429910)

### Infrastructure & Tooling - Beran

Beran first entered the crypto space in 2013 as an airdrop hunter and re-engaged in 2024 with a broader focus on technical participation. Since then, he has expanded into **node operations** across multiple networks, including Cortensor.

With a growing interest in infrastructure, Beran applied his basic coding skills to develop a custom app for monitoring and operational support—bridging the gap between user activity and technical contribution.

As part of Cortensor, he supports the network as a **community node operator** and continues to explore lightweight tooling to enhance network reliability and transparency.

X: @beranalpagion\
Telegram: @beranalpagion

### Infrastructure & Tooling - Heed

Heed is a full-stack developer with a strong focus on **blockchain infrastructure and validator operations**. He has built and maintained high-availability validator nodes, monitoring tools, and blockchain explorers across **Solana, EVM, and Cosmos ecosystems**.

As a contributor to Cortensor, Heed developed a **web-based chat interface** powered by the Cortensor inference SDK, and has helped improve **node operator onboarding** through hands-on documentation support.

His recent work includes building **multi-node orchestration tools** using Docker Compose for fast testnet deployment. Heed continues to focus on **decentralized infrastructure**, open-source tooling, and developer experience through automation and support apps.\
\
X : @mrheed\_\
Telegram : @blcryc\
Discord : @mrsyhd


# Copy of Team & Contributors

Cortensor was founded by a group of experienced engineers and entrepreneurs with deep expertise in distributed systems, blockchain infrastructure, and AI platforms. While the project was initiated by a core team, Cortensor is developed through decentralized, community-driven collaboration with contributors from around the world.

### Our Background

The founding team & contributors have:

* Successfully exited two traditional VC-backed startups
  * One acquired by a multinational trillion-dollar internet/software company
  * Another acquired by a fintech unicorn
* Led enterprise blockchain and DePIN projects, with a focus on decentralized networking and data infrastructure
* Built and scaled large distributed systems from concept to production, leveraging ledger and blockchain technologies

This experience laid the groundwork for Cortensor’s core principles: scalable, verifiable, and decentralized AI infrastructure, built in the open and shaped by a global community.

#### What Cortensor builds - <https://x.com/CryptoRyuma/status/1920280892238672256>

***

### Engineering

The lead architect graduated from the University of Southern California (USC) in Computer Science in 2011 and joined Google through a $100M acquisition. Over the last decade, he has contributed to major infrastructure projects in gaming, mobile OS, cloud computing, blockchain, and fintech.

**Previous Roles and Achievements:**

* Co-founded a DePIN startup acquired in 2020 by a Silicon Valley fintech unicorn
* Led backend infrastructure for games with over 100 million users
* Contributed to key Google projects, including Chrome Mobile, Android OS, and Google Cloud

He now helps to lead architectural efforts within Cortensor—working alongside the broader community—to build a decentralized, verifiable AI network based on Proof-of-Inference and open infrastructure. The project prioritizes trust, transparency, and global collaboration over centralized control.

* <https://www.linkedin.com/in/jonghyeopkim>

### Operation

Shelby has a background in IT with a bachelor-level degree and is now full-time in trading and crypto operations. Known for a high standard of quality and integrity, Shelby has worked as a trusted mod in a few carefully selected projects, always prioritizing transparency and long-term value.

A core contributor to Cortensor since the early days, Shelby plays a key role in community management across Telegram, Discord, and X, while also supporting internal coordination, operational planning, and node operator onboarding.

From organizing daily workflows to helping streamline support and validator processes, Shelby brings consistency and clarity to Cortensor’s decentralized operations.

Telegram: [shelby\_xb](https://t.me/shelby_xb)\
X: [cryptdshelby](https://x.com/cryptdshelby)

***

### Infrastructure & DevOps - Agnc

Agnc entered the crypto space in 2015, starting as a miner, node operator, and airdrop hunter. By 2019, he shifted focus toward technical infrastructure, bringing a background in technical sales and system administration to Web3 operations.

As one of the early Cortensor node operators, Agnc helps run and maintain the Cortensor RPC infrastructure, supporting node onboarding and validator uptime. He brings hands-on expertise in server setup, system monitoring, and infra maintenance, with a strong emphasis on reliability and clarity.

Agnc continues to support the Cortensor network’s infrastructure backbone, contributing to smooth operations across testnet and DevNet environments.\
\
Telegram: [centertopup](https://t.me/centertopup)\
X: [01\_choose](https://x.com/01_choose)

### Infrastructure & DevOps - RayRedd

In crypto since 2012, RayRedd began as an early miner and airdrop hunter. In 2024, he shifted focus to validator infrastructure, combining his DevOps background with a passion for onboarding new node operators through his Telegram channel.

He brings hands-on experience in server ops, monitoring, and network maintenance, and actively validates on: Cortensor, Aztec, CrossFi, Symphony, Empeiria, Airchains, Warden, and Humanode.

At Cortensor, he supports validator operations, node onboarding, and infrastructure coordination.

Telegram: [CryptoNodeRedd](https://t.me/CryptoNodeRedd) \
X: [0xRedd ](https://x.com/0xRedd)\
Discord: @rayredd

### Infrastructure & Tooling - Scerb

Scerb is an engineer and CTO of an R\&D company, with multiple granted patents in his field. With a long-standing interest in crypto and AI, he brings a forward-looking mindset and technical depth to decentralized infrastructure.

As a contributor to Cortensor, Scerb operates and maintains RPC infrastructure, builds tooling and watchdog systems, and supports node operators across environments. His work helps ensure network reliability and performance as the system scales.

Combining real-world engineering expertise with a passion for emerging tech, Scerb continues to expand Cortensor’s operational backbone with precision and care.

Telegram: Bo\
X: [Will429910](https://x.com/Will429910)

### Infrastructure & Tooling - Beran

Beran first entered the crypto space in 2013 as an airdrop hunter and re-engaged in 2024 with a broader focus on technical participation. Since then, he has expanded into **node operations** across multiple networks, including Cortensor.

With a growing interest in infrastructure, Beran applied his basic coding skills to develop a custom app for monitoring and operational support—bridging the gap between user activity and technical contribution.

As part of Cortensor, he supports the network as a **community node operator** and continues to explore lightweight tooling to enhance network reliability and transparency.

X: @beranalpagion\
Telegram: @beranalpagion

### Infrastructure & Tooling - Heed

Heed is a full-stack developer with a strong focus on **blockchain infrastructure and validator operations**. He has built and maintained high-availability validator nodes, monitoring tools, and blockchain explorers across **Solana, EVM, and Cosmos ecosystems**.

As a contributor to Cortensor, Heed developed a **web-based chat interface** powered by the Cortensor inference SDK, and has helped improve **node operator onboarding** through hands-on documentation support.

His recent work includes building **multi-node orchestration tools** using Docker Compose for fast testnet deployment. Heed continues to focus on **decentralized infrastructure**, open-source tooling, and developer experience through automation and support apps.\
\
X : @mrheed\_\
Telegram : @blcryc\
Discord : @mrsyhd


# Getting Started

As we prepare for the launch of our closed alpha testing, here are some essential notes to help you get started:

**System Requirements:**

* **Operating Systems:**
  * **Linux**: Currently supported. We plan to expand support to Windows and macOS after the closed alpha testing phase.
* **Software Dependencies:**
  * **Python and Docker**: Required for running Cortensor, managing dependencies, and ensuring consistent performance.
* **Hardware Requirements:**
  * **CPUs**: Must support AVX, AVX2, or AVX512 (for x86 architectures).
  * **Models**: Initially, only 4-bit quantized models will be supported, enabling broad hardware compatibility. Over time, we'll introduce higher bit options and support non-quantized models.

**Model Support:**

* **LLaMA Models**: Cortensor will initially support LLaMA models, with plans to gradually include additional open-source models as the platform evolves.

**Alpha Phase Overview:**

* **Quantized Models**: Focus on quantized models to ensure wide device compatibility during the alpha phase.
* **Development**: The alpha phase will focus on testing and refining the platform. Your participation is key to shaping Cortensor’s future.

**Next Steps:**

* Detailed installation and setup instructions will be provided as we progress. Prepare your environment according to the requirements above and stay tuned for updates.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Quick Start Guide

Welcome to the **Cortensor Quick Start Guide!** As we move forward with the development of our platform, here are some essential notes to help you get started:

***

## **Operating System Requirements**

* **Cross-Platform Support:** Cortensor is now fully supported on **Linux, Windows, and macOS**.
* **Python and Docker:** You'll need **Python** and **Docker** installed on your system to run Cortensor. These tools are essential for managing dependencies and containerizing the Cortensor environment.

***

## **Model Support**

* **Quantized & Non-Quantized Models:** Cortensor now supports **both quantized and non-quantized models**, ensuring broader compatibility across various hardware configurations.
* **Expanding Model Support:** We will continue expanding support for additional model types as development progresses.

***

## **Hardware Requirements**

* **CPU/GPU Compatibility:** Cortensor now supports **both CPUs and GPUs** across all platforms (**Linux, Windows, and macOS**).
* ~~**Broader CPU Support:** Unlike earlier versions, **AVX instruction sets (AVX, AVX2, AVX512) are no longer required**. Lower-end CPUs without AVX instructions are now supported.~~
* **Quantization Levels:** Initial inference will support **4-bit quantization**, ensuring efficient processing on a variety of CPUs. Additional quantization options and non-quantized models will be introduced over time.

***

These are just the first steps—stay tuned for **detailed setup instructions and updates** as we continue improving the platform!&#x20;

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# System Requirements

## **Supported Platforms**

### **Platform Support**

Cortensor now supports **Linux, Windows, and macOS** platforms, providing broader accessibility for users across different operating systems.

### **CPU Requirements**

Cortensor supports **both high-end and lower-end CPUs**, including those with and without **AVX instruction sets** (AVX, AVX2, AVX512). This ensures compatibility across a wide range of devices while maintaining efficient AI inference capabilities.

### **GPU Support**

Cortensor fully supports **GPU acceleration** across **Linux, Windows, and macOS**, enabling faster and more efficient AI inference for complex and resource-intensive workloads.

***

## **Software Dependencies**

### **Python**

Python is required to run Cortensor, as it handles various scripting, automation, and model execution tasks within the platform.

### **Docker**

Docker is necessary for containerizing the Cortensor environment, ensuring consistent performance, easier deployment, and management of dependencies across different operating systems.

***

## **Current and Future Support**

Cortensor has expanded its support to **Windows, macOS, and Linux**, alongside both **CPU- and GPU-based** processing. Future updates will continue enhancing **performance optimizations**, **additional hardware compatibility**, and **broader model support** to further improve accessibility and efficiency.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Installation & Setup

### DRAFT

**NOTE**: We are currently in the closed alpha phase for precursor miner testing. To set up and run the process below, you’ll need test ETH on Arbitrum Sepolia for your miner’s address. After generating the key from `cortensord`, you can obtain test ETH from a public faucet or contact us, and we’ll send some test ETH on Arbitrum Sepolia.

## 1. Download

### 1a. Download Installer

```
$ curl -L https://github.com/cortensor/installer/archive/main.tar.gz -o cortensor-installer-latest.tar.gz
$ tar xzfv cortensor-installer-latest.tar.gz
$ cd installer
```

### 1b. Clone Installer

```
# installer requires Git LFS
$ sudo apt install git-lfs

$ git clone https://github.com/cortensor/installer
$ cd installer
$ git lfs install
$ git lfs fetch
$ git lfs pull
$ git pull
```

### Git for Windows User

```
1. Download Git for Windows Standalone Installer from official website
https://git-scm.com/downloads/win

2. double-click install-git.bat under installer\win-bat
```

## 2. Installation & Setup

### Linux - Ubuntu 22.04 & Debian 12

#### Install - Docker, IPFS & Cortensord

```
# Run it as 'root'
$ cd installer

# Install Docker for ubuntu 22.04
$ ./install-docker-ubuntu.sh

# Install Docker for debian
$ ./install-docker-debian.sh

# Install IPFS
$ ./install-ipfs-linux.sh

# Install Cortensord
$ ./install-linux.sh

# Copy installer folder to deploy home
$ cp -Rf ./installer /home/deploy/installer
$ chown -R deploy.deploy /home/deploy/installer

# Logoff or start another shell
$ sudo su deploy
$ cd ~/

# Verify installation
$ ls -al /usr/local/bin/cortensord
$ ls -al $HOME/.cortensor/bin/cortensord
$ ls -al /etc/systemd/system/cortensor.service
$ ls -al $HOME/.cortensor/bin/start-cortensor.sh
$ ls -al $HOME/.cortensor/bin/stop-cortensor.sh
$ docker version
$ ipfs version
```

#### Setup - Your address needs to be whitelisted in advance by Cortensor Admin

<pre><code><strong># switch account to 'deploy' which was created from previous install step
</strong>$ sudo su deploy
$ cd ~/

$ export PATH=$PATH:~/.cortensor/bin

#################################
# Using helper scripts
$ cd ./installer

# Generate Key for the node via script
$ ./utils/gen-key.sh

# Please contact Cortensor support or mod to whitelist your address
$ ./utils/register.sh
$ ./utils/verify.sh
 
or 

#################################
# Using direct commands

# Geenerate Key for the node
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool gen_key

# Please contact Cortensor support or mod to whitelist your address
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool register
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool verify
</code></pre>

#### Start & Stop through SystemD

```
$ sudo su deploy
$ sudo systemctl start cortensor
$ sudo systemctl stop cortensor
```

#### Start MinerV2 Manually (With LLM engine docker)

```
$ sudo su deploy
$ export PATH=$PATH:~/.cortensor/bin
$ cd ~/.cortensor && cortensord ~/.cortensor/.env minerv2 1 docker

# or use script to start & stop
$ sudo su deploy
$ cd ~/.cortensor && ~/.cortensor/bin/start-cortensor.sh
$ cd ~/.cortensor && ~/.cortensor/bin/stop-cortensor.sh
```

#### Start MinerV2 Manually (With LLM engine as subprocess)

```
$ sudo su deploy
$ export PATH=$PATH:~/.cortensor/bin
$ cd ~/.cortensor && cortensord ~/.cortensor/.env minerv2
```

***

### OSX/Darwin - ARM64

#### Install - IPFS & Cortensord

```
$ cd installer

# Install IPFS
$ ./install-ipfs-osx.sh

# Install Cortensord
$ ./install-osx.sh

# Logoff or start another shell

# Verify installation
$ ls -al $HOME/.cortensor/bin/cortensord
$ ls -al $HOME/.cortensor/bin/start-cortensor.sh
$ ls -al $HOME/.cortensor/bin/stop-cortensor.sh
$ $HOME/.cortensor/bin/ipfs version
```

#### Setup - Your address needs to be whitelisted in advance by Cortensor Admin

```
$ cd ~/

$ export PATH=$PATH:~/.cortensor/bin

#################################
# Using helper scripts
$ cd ./installer

# Generate Key for the node via script
$ ./utils/gen-key.sh

# Please contact Cortensor support or mod to whitelist your address
$ ./utils/register.sh
$ ./utils/verify.sh
 
or 

#################################
# Using direct commands

# Geenerate Key for the node
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool gen_key

# Please contact Cortensor support or mod to whitelist your address
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool register
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool verify
```

#### Start & Stop through start & stop scripts

```
$ $HOME/bin/start-cortensor.sh
$ $HOME/bin/stop-cortensor.sh
```

#### Start MinerV2Manually

```
$ cd ~/.cortensor && $HOME/bin/cortensord ~/.cortensor/.env minerv2
```

### Windows Cygwin - AMD64

#### Install - Git Bash & Python

```
1. Install Git for Windows

Download Git for Windows Standalone Installer from official website
https://git-scm.com/downloads/win

or double-click ./installer/win-bat/install-git.bat to install Git

2. Install Python 3.13 (Optional)
```

#### Install - IPFS & Cortensord

```
$ cd installer

# Install IPFS
$ ./install-ipfs-win-cygwin.sh

# Install Cortensord
$ ./install-win-cygwin.sh

# Logoff or start another cygwin shell

# Verify installation
$ ls -al $HOME/.cortensor/bin/cortensord
$ ls -al $HOME/.cortensor/start-cortensor.sh
$ ls -al $HOME/.cortensor/stop-cortensor.sh
$ $HOME/.cortensor/bin/ipfs version
```

#### Setup - Your address needs to be whitelisted in advance by Cortensor Admin

<pre><code>$ cd ~/

$ export PATH=$PATH:~/.cortensor/bin

#################################
# Using helper scripts
$ cd ./installer

# Generate Key for the node via script
$ ./utils/gen-key.sh

# Please contact Cortensor support or mod to whitelist your address
$ ./utils/register.sh
$ ./utils/verify.sh
 
or 

#################################
# Using direct commands

<strong># Geenerate Key for the node
</strong><strong>$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool gen_key
</strong><strong>
</strong><strong># Please contact Cortensor support or mod to whitelist your address
</strong>$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool register
$ $HOME/.cortensor/bin/cortensord ~/.cortensor/.env tool verify
</code></pre>

#### Start & Stop through start & stop scripts

```
$ $HOME/.cortensor/start-cortensor.sh
$ $HOME/.cortensor/stop-cortensor.sh
```

#### Start MinerV2 Manually - Run under deploy user account

```
$ export PATH=$PATH:~/.cortensor/bin
$ cd ~/.cortensor && $HOME/.cortensor/bin/cortensord ~/.cortensor/.env minerv2
```

### Windows Cygwin - AMD64 through BAT files

#### Install - Git Bash & Python

```
1. Install Git for Windows

Double-click ./installer/win-bat/install-git.bat to install Git

2. Install Python 3.13 (Optional)
```

#### Install - IPFS & Cortensord

```
# Install Cortensor
Double-click ./installer/win-bat/install-cortensor.bat

# Install IPFS
Double-click ./installer/win-bat/install-ipfs.bat

# There will be start-cortensor.bat on Desktop
```

#### Setup - Your address needs to be whitelisted in advance by Cortensor Admin

```
# Generate Key
Double-click ./installer/win-bat/gen-key.bat

# Register
Double-click ./installer/win-bat/register.bat

# Verify
Double-click ./installer/win-bat/verify.bat

# Start
Double-click start-cortensor.bat on Desktop
```

#### Start & Stop through start & stop scripts

```
$ $HOME/.cortensor/start-cortensor.sh
$ $HOME/.cortensor/stop-cortensor.sh
```

#### Start MinerV2 Manually - Run under deploy user account

```
$ export PATH=$PATH:~/.cortensor/bin
$ cd ~/.cortensor && $HOME/.cortensor/bin/cortensord ~/.cortensor/.env minerv2
```

### Enable GPU support

\
Update .env file to enable GPU support

```
# Update .env file to enable GPU support

# Update to 1
LLM_OPTION_GPU=1

# Leave to -1 as automatic mode or you can configure your threshold
# number of LLM layers to be offload to GPU
LLM_OPTION_GPU_THRESHOLD=-1

# To start with GPU support, you need to use subprocess for LLM engine
$ cortensord ~/.cortensor/.env minerv2
```

## 3. Upgrade

### Linux - Ubuntu 22.04 & Debian

<pre><code>$ sudo su deploy
$ cd installer
<strong>$ git pull
</strong>$ ./upgrade-linux.sh
</code></pre>

### OSX/Darwin - ARM64

```
$ cd installer
$ git pull
$ ./upgrade-osx.sh
```

### Windows Cygwin - AMD64

```
$ cd installer
$ git pull
$ ./upgrade-win-cygwin.sh
```

## Debugging & Troubleshoot

Kill IPFS process - Windows, OSX, Linux

```
$ sudo su deploy
$ cd ./installer
$ ./utils/kill-ipfs.sh
```

### Debugging & Troubleshoot (Linux)

\
Check Log

```
$ ls -alh /var/log/cortensord.log
$ tail -f /var/log/cortensord.log
```

Check Node Address & ID

```
$ export PATH=$PATH:~/.cortensor/bin
$ /usr/local/bin/cortensord ~/.cortensor/.env tool id
```

Check NodeStats

```
$ export PATH=$PATH:~/.cortensor/bin
$ /usr/local/bin/cortensord ~/.cortensor/.env tool stats
```

Kill IPFS process - Linux & OSX

```
$ pkill ipfs
```

***

## Contributions from Community Members

### Documentations from Community Members

* <https://logosnodos.medium.com/step-by-step-how-to-install-cortensor-mining-ai-155b625213cb>
* <https://docs.aldebaranode.xyz/guide/testnet/cortensor/installation>
* <https://docs.cryptonode.id/en/testnet/cortensor>
* <https://github.com/coinsspor/Cortensor-Ag-Uzerinde-Coklu-Node-Kurulum-Rehberi--Phase-3---Devnet-4>
* <https://docs.logosnodos.online/testnet-node/cortensor>

### Node Monitoring Bots

* <https://t.me/conomo_bot>
* <https://t.me/cortensormonitorbot>

### Node Watchdogs

* [https://github.com/scerb/node\_watch](https://github.com/scerb/node_watch/releases)
* <https://github.com/beranalpa/cortensor-watcher-bot>

### RPC Endpoints

* <https://forms.gle/D3cMJnLFZKQAvPL3A>
* <https://sepolia-arb-rpc.centertopup.com/>
* <https://arb-sep.scerb.uk/>

### Arbitrum Sepolia Faucet Bots

* <https://t.me/Cortensor_Faucet_Bot>

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Getting Test ETH

This guide provides step-by-step instructions on how to acquire test ETH and bridge it to the Arbitrum Sepolia testnet. Having test ETH is essential for interacting with the Cortensor network in the development and testing phases.

## **Step 1: Acquire Test ETH from a Faucet**

1. **Find a Test ETH Faucet**\
   Access a trusted faucet where you can get test ETH. Examples include:
   * [Sepolia Faucet on Alchemy](https://sepoliafaucet.com)
   * [Sepolia Faucet on Paradigm](https://faucet.paradigm.xyz)
2. **Request Test ETH**\
   Enter your wallet address and complete any CAPTCHA requirements. Click the “Send” or “Request” button to receive test ETH in your wallet.

## **Step 2: Connect to Arbitrum Sepolia Network**

1. **Add Arbitrum Sepolia Network to MetaMask (if not added)**
   * Open MetaMask, go to **Settings > Networks**, and click **Add Network**.
   * Fill in the following details:
     * **Network Name:** Arbitrum Sepolia Testnet
     * **New RPC URL:** `https://sepolia.arbitrum.io/rpc`
     * **Chain ID:** `421613`
     * **Currency Symbol:** ETH
     * **Block Explorer URL:** <https://sepolia-explorer.arbitrum.io/>
2. **Switch to the Arbitrum Sepolia Network**\
   Open MetaMask and select the Arbitrum Sepolia network from the dropdown.

## **Step 3: Bridge ETH to Arbitrum Sepolia**

1. **Access the Arbitrum Bridge**\
   Go to the official Arbitrum Bridge:\
   <https://bridge.arbitrum.io/>
2. **Connect Wallet**\
   Click on **Connect Wallet** and choose MetaMask or your preferred wallet. Ensure that it’s connected to the Sepolia network.
3. **Initiate the Bridge Transfer**
   * In the **From** section, select the Sepolia network and choose ETH.
   * In the **To** section, choose **Arbitrum Sepolia**.
   * Enter the amount of ETH you wish to bridge and confirm the transaction.
4. **Approve and Confirm**\
   After initiating the bridge, you’ll need to approve and confirm the transaction in your wallet. Once confirmed, your test ETH will be available on Arbitrum Sepolia.

## **Additional Notes**

* It may take a few minutes for the transaction to complete and for the test ETH to appear on Arbitrum Sepolia.
* If you encounter any issues, check the transaction status on the Sepolia and Arbitrum explorers linked above.

Once your test ETH is on Arbitrum Sepolia, you’re ready to interact with the Cortensor test environment!


# Setup Own RPC Endpoint

#### Setting Up Your Own RPC Endpoint for Cortensor with Popular Providers

Using your own RPC endpoint enhances reliability and performance when interacting with the Cortensor network. Below are instructions for setting up an RPC endpoint with some of the most popular blockchain infrastructure providers: **Ankr**, **Alchemy**, **QuickNode**, and **ChainStack**.

***

## **1. Ankr**

Ankr offers decentralized Web3 infrastructure, including free and paid RPC endpoints.

**Setup Steps:**

1. **Visit** [Ankr RPC](https://www.ankr.com/).
2. **Sign Up / Log In:** Create an account or log in.
3. **Select Blockchain:** Go to the **RPC endpoints** section, select the **Ethereum Sepolia** network, and choose **Arbitrum Sepolia** for compatibility.
4. **Generate Endpoint:** Click to generate a unique endpoint URL, which you can use in your wallet or application.
5. **Connect RPC to Wallet:** Copy the endpoint URL and add it as a custom RPC in your wallet.

***

## **2. Alchemy**

Alchemy offers reliable RPC services with high performance, suited for large-scale applications.

**Setup Steps:**

1. **Visit** [Alchemy](https://www.alchemy.com/).
2. **Sign Up / Log In:** Create an Alchemy account or log in.
3. **Create an App:** Go to your dashboard and click **Create App**. Select **Ethereum** as the blockchain, and choose **Sepolia** or **Arbitrum Sepolia** based on your needs.
4. **Get API Key:** After creating the app, an RPC URL will be generated with an API key. Copy this URL.
5. **Add to Wallet:** Use the URL as a custom RPC endpoint in your wallet for Cortensor interactions.

***

## **3. QuickNode**

QuickNode provides Web3 infrastructure that allows custom API endpoints for various chains.

**Setup Steps:**

1. **Visit** [QuickNode](https://www.quicknode.com/).
2. **Sign Up / Log In:** Create an account or log in.
3. **Add Endpoint:** Click **Create Endpoint** and select the **Ethereum Sepolia** or **Arbitrum Sepolia** chain. Configure any options as needed.
4. **Copy Endpoint URL:** QuickNode will generate a custom RPC URL; copy it for later use.
5. **Wallet Configuration:** Paste the endpoint URL in your wallet’s custom RPC settings.

***

## **4. ChainStack**

ChainStack offers enterprise-grade infrastructure with customizable RPCs for public blockchains.

**Setup Steps:**

1. **Visit** [ChainStack](https://chainstack.com/).
2. **Sign Up / Log In:** Register for an account or log in.
3. **Deploy Node:** Choose **Ethereum** and select the **Sepolia** or **Arbitrum Sepolia** testnet option. Configure as needed and deploy.
4. **Copy RPC URL:** Once your node is deployed, ChainStack will provide an RPC endpoint URL.
5. **Add to Wallet:** Paste this URL in your wallet as a custom RPC.

***

## Using Your Custom RPC with Cortensor

1. **Open MetaMask (or another compatible wallet)** and go to **Settings > Networks**.
2. Click **Add Network** and enter the following fields:
   * **Network Name:** Cortensor on Arbitrum Sepolia (or your preferred network name)
   * **New RPC URL:** Paste your custom RPC URL from one of the providers above
   * **Chain ID:** Based on your chosen chain, such as 421614 for Arbitrum Sepolia
   * **Currency Symbol:** ETH
   * **Block Explorer URL:** <https://sepolia-explorer.arbitrum.io/>
3. **Save and Switch Networks:** You’re now ready to interact with Cortensor using your custom RPC setup!

Using custom RPC endpoints allows for faster and more reliable access, which is especially valuable for intensive operations on the Cortensor decentralized AI inference network.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Router Node Setup

## <mark style="color:red;">WIP - THIS IS EARLY DRAFT</mark>

## Overview

The **Router Node** acts as a **Web2-compatible RESTful API endpoint**, enabling seamless integration of existing Web2 applications into the Cortensor network. It provides **OpenAI-compatible APIs**, allowing developers to integrate AI inference functionality as effortlessly as a hotswap—without modifying their core infrastructure.

While this Router Node is **privately hosted**, it mirrors the behavior of a public gateway by bridging external requests with Cortensor’s internal session flow.

For Web3 applications and smart contracts, direct interaction with the **Session** and **Session Queue** modules is supported, bypassing the Router Node to operate in a fully decentralized and trustless manner.

This setup empowers developers to serve both traditional and decentralized clients while participating in Cortensor’s distributed AI inference network.

> **Note:** The Router Node setup follows the same process as a standard Cortensor node with additional configuration for API access.

***

### Prerequisites

Before starting, ensure the following:

* You’ve followed the [Cortensor Node Setup Guide](https://docs.cortensor.network/getting-started/installation-and-setup) to install `cortensord` and IPFS.
* Your environment is properly configured with required dependencies and keys.
* You are running a compatible system (Linux, macOS, or Windows).

***

## Installation Steps

#### 1. Install `cortensord` and IPFS

Follow the [installation instructions](https://docs.cortensor.network/getting-started/installation-and-setup) to install:

* `cortensord` (Cortensor daemon)
* IPFS (InterPlanetary File System)

#### 2. Generate Node Keys

Use the key generation process described in the node setup documentation to generate necessary identity and signing keys.

***

### Configuration

#### 3. Update Environment File (`.env`)

Ensure the following variables are present and configured in your `.env` file:

```bash
# Enable API
API_ENABLE=1

# Generate a unique API key
API_KEY=f18a7432-4d1e-47a9-a352-81145275809a

# Set your API port
API_PORT=5010

# Router External IP and Port for Miner Communication
# Used for external access to the router
ROUTER_EXTERNAL_IP="192.168.250.221"
ROUTER_EXTERNAL_PORT="9001"

# Router REST Bind IP and Port for Client Communication
# Reverse proxy to this IP and port
ROUTER_REST_BIND_IP="127.0.0.1"
ROUTER_REST_BIND_PORT="5010"
```

#### 4. Generate a New API Key

You can generate a secure API key using the following command:

```bash
cortensord ~/.cortensor/.env tool gen-api-key
```

Copy and paste the generated key into your `.env` under `API_KEY`.

***

### Launching the Router Node

**4. Create a Session from the Dashboard**

Before starting your Router Node, create a session via the Cortensor Dashboard:\
🔗 <https://dashboard-alpha.cortensor.network/session>

#### 5. Start the Router Node

Use the following command to start your router node:

```bash
cortensord ~/.cortensor/.env routerv1
```

Upon startup, your router node will:

* Register itself to handle session routing
* Open API access on the configured port (default: `5010`)
* Begin communication with miners over WebSocket
* Accept and relay inference tasks from clients

***

### Post-Setup: API Access

Once the router node is running, you can:

* Use the Web2 REST API to create sessions and submit inference tasks
* Monitor inference data as it streams between your node and miners
* Integrate Cortensor AI functionality into applications via SDKs or custom integrations

For more details on API endpoints and usage, visit:\
📘 [API Reference](/getting-started/web2-api-reference)

***

### Notes

* The router node does **not** perform inference—it coordinates task flow between users and miners.
* Your node must remain online and responsive to maintain API availability.
* In future releases, additional features such as task prioritization, caching, and rate limits may be configurable.

***

By hosting your own router node, you gain private access to Cortensor’s decentralized AI inference capabilities, with full control over task submission, request routing, and session monitoring.


# Dedicated Ephemeral Node Setup

### Overview

A **Dedicated Ephemeral Node** allows a user to directly assign their own miner (inference node) to a session they have created. This setup is ideal for private use cases or testing, where task routing bypasses automatic node selection logic.

This mechanism is similar to regular ephemeral miners but introduces manual pairing of node and session by the user.

> ⚠️ Note: No authentication is enforced yet. Access control and auth mechanisms will be introduced in upcoming updates.

***

### Prerequisites

Before you begin, ensure you have followed the general installation instructions:

📖 [Installation and Setup Guide](https://docs.cortensor.network/getting-started/installation-and-setup)

This includes:

* Installing `cortensord`
* IPFS setup
* Environment configuration
* Docker installation

***

### Key Differences from Standard Miner Setup

| Component          | Regular Miner                                        | Dedicated Ephemeral Node                 |
| ------------------ | ---------------------------------------------------- | ---------------------------------------- |
| Startup Command    | `minerv4` or default                                 | `minerv4`                                |
| Session Assignment | Automatically selected via router & reputation logic | Manually assigned to session you control |
| Authorization      | Session, Session Queue & Session Auth                | N/A (auth coming soon)                   |

***

### How to Start

1. **Update `.env` File**\
   Ensure your environment file is configured with the correct values, especially:

   ```env
   CONTRACT_ADDRESS_RUNTIME=<runtime_contract_address>

   ...

   # Dedicated Node Configuration
   #-----------------------------------------------------------
   # Set to 1 to run as a dedicated node (instead of ephemeral)
   ENABLE_DEDICATED_NODE=1
   # Comma-separated list of session IDs this node is authorized to serve
   # Example: "0,1,2,3,4,5"
   DEDICATED_NODE_AUTHORIZED_SESSIONS="<your_session_id>"
   ```

   1. Replace `<your_session_id>` with the ID of the session you want to dedicate this node to (e.g., the session ID shown in the dashboard).
2. **Start as Dedicated Ephemeral Miner**\
   Use the following startup command:

   ```bash
   cortensord ~/.cortensor/.env minerv4 1 docker
   ```
3. Use the **"**&#x44;edicated Node&#x73;**"** interface to input your node’s address (i.e., the address your miner is registered with).

***

### Use Case

Dedicated Ephemeral Nodes are useful when:

* You want complete control over which node handles your inference.
* You’re testing or debugging inference performance privately.
* You’re building custom integrations with known node-session bindings.

***

### What’s Next

* Authentication & validation will be added soon to prevent misuse.


# Reverse Proxy Setup

To prepare your Cortensor Router Node for production use and support future scaling, it is recommended to set up an Nginx reverse proxy in front of your API service. This setup enables secure HTTPS access, controlled endpoint exposure, and load distribution across multiple router nodes.

### Why Use a Reverse Proxy?

* **Production-Ready Architecture**: Adds SSL, security headers, CORS, and configurable access control.
* **Scalability**: Makes it easier to load balance requests across multiple router nodes.
* **Security**: Hides internal ports and enables HTTPS via Let's Encrypt.
* **Routing Control**: Restricts access to specific endpoints and protects internal services.

***

### Setup Guide

#### 1. Prerequisites

* A running Cortensor Router Node (`cortensord ~/.cortensor/.env routerv1`)
* Public domain pointing to your VPS (e.g., `router.example.com`)
* Root access (`sudo`) on your node server
* Ports `80` and `443` open on your firewall

***

#### 2. Installation Script

Run the official Cortensor Nginx installer on your Router Node host:

```bash
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/cortensor/installer/main/install-nginx-linux.sh)"
```

This will:

* Install Nginx and Certbot
* Prompt you to enter your domain
* Use the preset template:\
  [router-node.nginx.template](https://github.com/cortensor/installer/blob/main/conf/router-node.nginx.template)
* Generate and apply a complete reverse proxy config for your Router Node
* Optionally install HTTPS using Let’s Encrypt

***

#### 3. API Server Configuration

Ensure your Router Node API is running on port `5010` (default):

```bash
cortensord ~/.cortensor/.env routerv1
```

Update your `.env`:

```env
API_ENABLE=1
API_KEY=<your_generated_key>
API_PORT=5010
```

***

#### 4. SSL Setup (Optional but Recommended)

If DNS is properly configured, the installer will prompt you to secure your router domain via Certbot. You can always run this manually later:

```bash
sudo certbot --nginx -d router.example.com
```

***

#### 5. Sample Architecture Diagram

```
Client (Web2/Web3) 
    ↓
Cloudflare or DNS/CDN
    ↓
Nginx Reverse Proxy (SSL + Routing)
    ↓
Router Node (REST API)
    ↓
Session Queue ↔ Miners
```

***

### Available Endpoints (by default)

The reverse proxy allows access only to these:

* `/api/v1/info`
* `/api/v1/status`
* `/api/v1/miners`
* `/api/v1/sessions`
* `/api/v1/completions`
* `/api/v1/tasks`
* `/api/v1/ping`

All other routes return `404`.

***

### CORS Configuration

The template includes both:

* **Restricted CORS**: Allow specific trusted origins
* **Permissive CORS**: (commented by default) allows all origins

Update CORS settings in:

```
/etc/nginx/sites-available/router-node.conf
```

***

### Maintenance Commands

```bash
# Restart Nginx after config changes
sudo systemctl restart nginx

# Check status
sudo systemctl status nginx
```

***

### Notes

* This setup is designed for **private router nodes**. Load balancing and auto-scaling support will be introduced in future versions.
* Make sure the API port (5010) is **not exposed publicly** when reverse proxy is enabled.

***

### What’s Next?

* Support for **multi-router failover**
* Integration with Cortensor Dashboard & Metrics
* Dynamic scaling across multiple router nodes


# Web2 API Reference

Web2 RESTful API Reference

> **Status**: WIP — Early Draft

This document provides a comprehensive reference for the RESTful API endpoints exposed by a [Cortensor Router Node](/getting-started/installation-and-setup/router-node-setup). These endpoints allow developers to interact with sessions, tasks, miners, and completions, enabling integration with AI inference workloads in Web2 applications.

***

### Authentication

All endpoints require a Bearer token passed via the `Authorization` header:

```http
Authorization: Bearer <api_key>
```

**Default Dev Token:** `default-dev-token`

***

### Base URL

All requests are relative to the Router's base URL:

```http
http://<router_host>:5010
```

For production, it is recommended to place the Router Node behind a reverse proxy (e.g. Nginx) for:

* TLS termination
* Rate limiting
* Load balancing
* Access control
* Hiding internal ports

***

### [Reverse Proxy](/getting-started/installation-and-setup/router-node-setup/reverse-proxy-setup) (Production Setup)

For production environments, it is strongly recommended to run the Router Node behind a reverse proxy like **Nginx**, **Caddy**, or **HAProxy**. This enhances security, scalability, and performance. The reverse proxy should forward requests to the Router's internal address (e.g., `127.0.0.1:5010`).

#### Benefits:

* TLS/SSL termination
* Request rate limiting
* Load balancing and retries
* Fine-grained access control
* IP whitelisting or firewall rules
* Prevents exposing internal ports to the public

***

### Endpoints

#### GET /api/v1/info

Returns basic metadata about the Router Node.

```bash
curl -X GET http://<router_host>:5010/api/v1/info \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/status

Returns current router status and health.

```bash
curl -X GET http://<router_host>:5010/api/v1/status \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/miners

Lists all currently connected miner nodes.

```bash
curl -X GET http://<router_host>:5010/api/v1/miners \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/sessions

Lists all active sessions.

```bash
curl -X GET http://<router_host>:5010/api/v1/sessions \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/sessions/{sessionId}

Returns metadata about a specific session.

**Path Param:** `sessionId` — numeric session ID

```bash
curl -X GET http://<router_host>:5010/api/v1/sessions/0 \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/tasks/{sessionId}

Lists all tasks under a given session.

```bash
curl -X GET http://<router_host>:5010/api/v1/tasks/0 \
-H "Authorization: Bearer <api_key>"
```

***

#### GET /api/v1/tasks/{sessionId}/{taskId}

Returns a specific task from a session.

```bash
curl -X GET http://<router_host>:5010/api/v1/tasks/0/0 \
-H "Authorization: Bearer <api_key>"
```

***

#### POST /api/v1/completions/{sessionId}

Submit an AI inference prompt using a session ID in the URL.

**Request Body:**

```json
{
  "prompt": "Hello, how are you?",
  "stream": false,
  "timeout": 60
}
```

```bash
curl -X POST http://<router_host>:5010/api/v1/completions/0 \
-H "Authorization: Bearer <api_key>" \
-d '{"prompt": "Hello, how are you?", "stream": false, "timeout": 60}'
```

***

#### POST /api/v1/completions

Submit a prompt with session ID included in the body.

**Request Body:**

```json
{
  "session_id": 0,
  "prompt": "Hello, how are you?",
  "stream": false,
  "timeout": 60
}
```

```bash
curl -X POST http://<router_host>:5010/api/v1/completions \
-H "Authorization: Bearer <api_key>" \
-d '{"session_id": 0, "prompt": "Hello, how are you?", "stream": false, "timeout": 60}'
```

***

### Streaming Completions

Setting `stream: true` in the request body returns real-time streamed responses using Server-Sent Events (SSE).

***

### Error Codes

| Code | Meaning               |
| ---- | --------------------- |
| 200  | Success               |
| 400  | Bad Request           |
| 401  | Unauthorized          |
| 404  | Not Found             |
| 500  | Internal Server Error |

***

### Usage Notes

* Compatible with OpenAI-style interfaces
* Designed for Web2 integrations via REST
* Supports private/local inference routing


# Web3 SDK Reference

> **Status**: WIP — Early Draft

This document provides a comprehensive reference for interacting with Cortensor smart contracts using the `ethers.js` library. It covers session and task management, along with contract event listening for dApp integrations.

***

### Setup

#### Required Dependencies

```bash
npm install ethers
```

#### Configuration

```javascript
const SESSION_V2_ADDRESS = "0x...";        // SessionV2 contract address
const SESSION_QUEUE_V2_ADDRESS = "0x...";  // SessionQueueV2 contract address
const PUBLIC_RPC_URL = "https://...";      // RPC URL for the network
```

#### Required ABIs

* `SessionV2.json` - ABI for the Session V2 contract
* `SessionQueueV2.json` - ABI for the Session Queue V2 contract

***

### Session Management

#### `create`

<pre class="language-solidity"><code class="lang-solidity">function create(
  string memory name,
  string memory metadata,
  address variableAddress,
  uint256 minNumOfNodes,
  uint256 maxNumOfNodes,
  uint256 redundant,
  uint256 numOfValidatorNodes,
  uint256 mode,
  bool reserveEphemeralNodes,
<strong>  uint256 sla,
</strong>  uint256 modelIdentifier,
  uint256 reservePeriod,
  uint256 maxTaskExecutionCount
) external;
</code></pre>

Creates a new session.

```js
const tx = await sessionContract.create(
  "My Session",
  "Metadata",
  await signer.getAddress(),
  1, 3, 1, 0, 0,
  false,
  0,
  0,
  300,
  5
);
await tx.wait();
```

***

#### `getSessions`

```solidity
function getSessionsByAddress(address userAddr) external view returns (Session[] memory);
```

Returns all sessions owned by a user address.

```js
const sessions = await sessionContract.getSessionsByAddress("0xYourAddress");
```

***

#### `getSession`

```solidity
function getSession(uint256 sessionId) external view returns (Session memory);
```

Returns details for a session by ID.

```js
const session = await sessionContract.getSession(0);
```

***

#### `getSessionMiners`

```solidity
function getEphemeralNodes(uint256 sessionId) external view returns (address[] memory);
```

Returns ephemeral miners assigned to a session.

```js
const miners = await sessionContract.getEphemeralNodes(0);
```

***

#### `updateSession`

```solidity
function update(
  string memory name,
  string memory metadata,
  uint256 sessionId,
  uint256 minNumOfNodes,
  uint256 maxNumOfNodes,
  uint256 redundant,
  uint256 numOfValidatorNodes,
  uint256 mode
) public;
```

Updates session configuration.

```js
await sessionContract.update(
  "Updated Name",
  "Updated Metadata",
  0, 2, 4, 2, 0, 0
);
```

***

### Task Management

#### `submit`

```solidity
function submit(
  uint256 sessionId,
  uint256 nodeType,
  string calldata taskData,
  uint256 promptType,
  string calldata promptTemplate,
  uint256[] calldata llmParams,
  string calldata clientReference
) external;
```

Submits a task to the session.

```js
await sessionContract.submit(
  0,
  0,
  JSON.stringify({ type: "chat", message: "Hello" }),
  0,
  "",
  [1024, 1, 1, 1, 0, 0],
  "my-client-side-reference"
);
```

***

#### `getTasksBySessionId`

```solidity
function getTasksBySessionId(uint256 sessionId) public view returns (Task[] memory);
```

Returns all tasks for a session.

```js
const tasks = await queueContract.getTasksBySessionId(0);
```

***

#### `getTaskResults`

```solidity
function getTaskResults(uint256 sessionId, uint256 taskId) public view returns (address[] memory, string[] memory);
```

Returns the results submitted by miners for a specific task.

```js
const [miners, results] = await queueContract.getTaskResults(0, 0);
```

***

### Events

#### SessionV2 Contract Events

* `SessionCreated(uint256 sessionId, bytes32 sid, address owner, address[] miners)`
* `SessionUpdated(uint256 indexed sessionId, address indexed updater, uint256 minNumOfNodes, uint256 maxNumOfNodes, uint256 redundant)`
* `SessionDeactivated(uint256 indexed sessionId, address indexed deactivator)`

***

#### SessionQueueV2 Contract Events

* `TaskQueued(uint256 sessionId, uint256 taskId, uint256 globalId, string taskData)`
* `TaskAssigned(uint256 sessionId, uint256 taskId, address[] miners)`
* `TaskEnded(uint256 sessionId, uint256 taskId, address[] miners)`

***

### Listening to Events

```js
const provider = new ethers.WebSocketProvider(PUBLIC_RPC_URL.replace('https', 'wss'));
const queueContract = new ethers.Contract(SESSION_QUEUE_V2_ADDRESS, SessionQueueV2ABI, provider);

queueContract.on("TaskEnded", (sessionId, taskId, miners, event) => {
  console.log(`Task ${taskId} in session ${sessionId} completed`);
});
```

***

### Notes

* Use a secure provider (e.g. Alchemy, Infura)
* Wrap contract calls in try/catch
* Monitor for transaction failures
* For production, use hardware wallets for signing

***

### Error Handling

```js
try {
  const tx = await contract.fn();
  await tx.wait();
} catch (error) {
  console.error("Contract call failed:", error);
}
```

***

### Session Modes

* `0`: Ephemeral — shared miner pool
* `1`: Hybrid — dedicated + ephemeral
* `2`: Dedicated — exclusively dedicated miners


# Core Concepts

Cortensor is built on a series of core concepts that collectively provide a robust and scalable framework for decentralized AI. These concepts ensure that the platform is not only efficient and secure but also fosters innovation and community collaboration.

### **Key Concepts**

1. **Decentralized AI Inference**
   * **Distributed Computing**: Utilizing a global network of nodes to perform AI inference tasks, reducing the dependency on centralized servers and increasing resilience and flexibility.
   * **Scalability**: Ensuring that AI inference can scale efficiently with the growing demands of users and applications.
2. **Community-Powered Network**
   * **Collaborative Ecosystem**: Encouraging contributions from a diverse community of developers, researchers, and users.
   * **Incentive Structures**: Implementing reward mechanisms to incentivize participation and innovation within the network.
3. **Multi-Layer Blockchain Architecture**
   * **Security and Transparency**: Using blockchain technology to secure transactions and ensure transparency within the network.
   * **Decentralized Governance**: Allowing the community to participate in decision-making processes, ensuring a fair and democratic platform.
4. **Incentive Structure**
   * **Token-Based Rewards**: Utilizing $CORTENSOR tokens to reward contributions and participation.
   * **Fair Compensation**: Ensuring that developers, validators, and users are fairly compensated for their efforts and resources.
5. **Universal AI Accessibility**
   * **Open-Source Models**: Providing access to a variety of open-source AI models, allowing for customization and unrestricted use.
   * **Lowering Barriers to Entry**: Making advanced AI technologies accessible to a broader audience, promoting widespread adoption and innovation.
6. **Gamification and Quality Control / PoUW**
   * **Gamified Node Evaluation**: Cortensor employs a gamified approach to evaluate and categorize inference nodes. Nodes participate in "games" where they generate blocks using LLM models, and other nodes evaluate and verify the results in a predictable and deterministic manner.
   * **Dynamic Capability Assessment**: This process allows Cortensor to continuously assess each node's capabilities, ensuring precise matching of inference tasks to appropriate nodes.
   * **Supply-Side Quality Control**: The gamified system ensures continuous quality assessment and categorization of nodes, maintaining a high standard of service and capability.
   * **Incentivized Participation**: Node operators are incentivized to participate in these games, improving their performance and contributing to a competitive and high-quality network.
   * **Service Quality Assurance**: By classifying nodes based on their capabilities, Cortensor ensures a high quality of service and reliability for end-users and services.
   * NOTE: PoUW extensibility
7. **Synthetic Data Generation (Byproduct of PoUW)**
   * **Synthetic Data as a Byproduct**: The gamification process generates significant amounts of question-answer data, which can be valuable for training and improving AI models, providing an additional benefit to the Cortensor ecosystem.
   * NOTE: using future PoUW to generate on-demand synthetic data generation framework

These core concepts form the backbone of Cortensor, providing the structure and principles that guide the platform's development and operation. By understanding these key elements, you will gain a deeper appreciation of how Cortensor is designed to democratize AI and foster a collaborative, innovative community.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Decentralized AI Inference

Cortensor's decentralized AI inference is a cornerstone of its architecture, designed to enhance robustness, scalability, and security in AI computations. This approach distributes AI inference tasks across a global network of nodes, reducing reliance on centralized servers and increasing overall system resilience.

## Key Features

### **Distributed Computing Network**

* Cortensor leverages a worldwide network of nodes to perform AI inference tasks.
* This distribution minimizes single points of failure and enhances system reliability.

### **Scalability**

* The network is designed to efficiently scale with growing user demands and application complexity.
* Dynamic allocation of resources ensures optimal performance across various workloads.

### **Hardware Flexibility**

* Cortensor supports a wide range of hardware, including CPUs and GPUs.
* Quantization techniques allow for efficient operation on diverse device types.

### **Intelligent Task Routing**

* Router nodes intelligently assign tasks to the most suitable inference nodes based on their capabilities.
* This ensures efficient resource utilization and optimal task performance.

## How It Works

1. **Task Submission**: Users or services submit AI inference tasks to the Cortensor network.
2. **Intelligent Routing**: Router nodes analyze the task requirements and available node capabilities.
3. **Task Distribution**: The task is assigned to appropriate inference nodes based on their performance metrics and current workload.
4. **Parallel Processing**: Multiple nodes may work on different aspects of a task simultaneously, enhancing speed and efficiency.
5. **Result Validation**: Guard/validation nodes verify the results to ensure accuracy and detect potential fraudulent activity.
6. **Result Delivery**: Verified results are securely delivered back to the user or service.

## Benefits

* **Enhanced Reliability**: Distributed architecture minimizes downtime and service interruptions.
* **Improved Performance**: Parallel processing and intelligent routing optimize task completion times.
* **Cost-Effective**: Users can access high-performance AI inference without investing in expensive hardware.
* **Privacy-Focused**: Decentralization inherently enhances data privacy by avoiding centralized data storage.

## Future Developments

Cortensor plans to expand its decentralized AI inference capabilities to support a wider range of AI models and use cases, including:

* Advanced natural language processing
* Computer vision tasks
* Predictive analytics
* Specialized domain-specific AI models

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Community-Powered Network

Cortensor's decentralized AI inference is fundamentally driven by its community, creating a collaborative ecosystem that fosters innovation and ensures the network's growth and sustainability.

### **Collaborative Ecosystem**

* Diverse community of developers, researchers, and users contribute to the network's development and expansion.
* Open-source approach encourages continuous improvement and innovation.

### **Incentive Structures**

* Token-based rewards ($COR) incentivize participation and high-quality contributions.
* Nodes earn tokens for performing network liveness checks, health checks, and serving user requests.
* Tiered reward system ensures nodes are consistently available and capable of handling AI tasks.

### **Supply-Side Development**

* Community members are encouraged to provide and run binary/system images, becoming stateless validators/ranking systems.
* Gamified approach with Level 1 (liveness checks) and Level 2 (capability assessment) fosters competition and ensures a robust network.

### How It Works

1. **Task Submission**: Users or services submit AI inference tasks to the Cortensor network.
2. **Intelligent Routing**: Router nodes analyze the task requirements and available node capabilities.
3. **Task Distribution**: The task is assigned to appropriate inference nodes based on their performance metrics and current workload.
4. **Parallel Processing**: Multiple nodes may work on different aspects of a task simultaneously, enhancing speed and efficiency.
5. **Result Validation**: Guard/validation nodes verify the results to ensure accuracy and detect potential fraudulent activity.
6. **Result Delivery**: Verified results are securely delivered back to the user or service.

### Benefits

* **Enhanced Reliability**: Distributed architecture minimizes downtime and service interruptions.
* **Improved Performance**: Parallel processing and intelligent routing optimize task completion times.
* **Cost-Effective**: Users can access high-performance AI inference without investing in expensive hardware.
* **Privacy-Focused**: Decentralization inherently enhances data privacy by avoiding centralized data storage.
* **Community-Driven Innovation**: Continuous improvement through community contributions and feedback.

#### Future Developments

Cortensor plans to expand its decentralized AI inference capabilities to support a wider range of AI models and use cases, including:

* Advanced natural language processing
* Computer vision tasks
* Predictive analytics
* Specialized domain-specific AI models

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Gamification and Quality Control

Cortensor employs an innovative approach to network development and quality assurance through gamification and a robust quality control system. This strategy ensures the continuous improvement of the network's capabilities while maintaining high standards of service.

## Proof of Useful Work (PoUW)

Cortensor implements a novel consensus mechanism called Proof of Useful Work (PoUW), which combines network security with practical AI tasks.

### Level 1: Network Liveness

* **Purpose**: Ensure basic functionality and responsiveness of inference nodes.
* **Process**:
  1. Randomly selected nodes generate short questions on selected topics.
  2. Other nodes provide completions for these questions.
  3. Validation nodes assess and score the responses.
* **Outcome**: Establishes a minimum performance threshold for node participation.

### Level 2: Capability Assessment

* **Purpose**: Evaluate and rank nodes based on their processing speed and capabilities.
* **Process**:
  1. Nodes are challenged with more complex AI tasks within time constraints.
  2. Performance is measured in terms of token speed and task completion quality.
* **Outcome**: Categorizes nodes based on their capabilities, enabling efficient task allocation.

## Gamified Supply-Side Development

Cortensor incentivizes network growth through a gamified approach:

1. **Public Participation**: Anyone can provide and run binary/system images to become validators.
2. **Competitive Environment**: Nodes compete to improve their performance and capabilities.
3. **Tiered Progression**: Nodes advance through levels, unlocking access to more complex tasks and higher rewards.

### Quality Control Mechanisms

### Intelligent Routing

* Router nodes analyze task requirements and node capabilities.
* Ensures optimal matching of AI inference tasks to appropriate nodes.

### Multi-Layer Validation

1. **Router Validation**: Initial check of task completion and basic quality assessment.
2. **Guard Node Validation**: In-depth verification of results and scoring for accuracy.
3. **Reputation System**: Nodes build reputation scores based on performance and result quality.

### Fraud Prevention

* Multiple validation nodes assess each task to detect and prevent malicious behavior.
* Consensus-based scoring system ensures fair and accurate evaluations.

### Benefits of Gamification and Quality Control

1. **Continuous Improvement**: Encourages nodes to upgrade their hardware and optimize performance.
2. **Dynamic Network Adaptation**: The network evolves to meet changing demands and technological advancements.
3. **High-Quality Results**: Rigorous validation ensures reliable and accurate AI inference outputs.
4. **Fair Reward Distribution**: Performance-based incentives align node operator interests with network goals.

## Synthetic Data Generation

As a byproduct of the PoUW process, Cortensor generates valuable synthetic data:

* **Use Cases**: Training data for AI models, benchmarking, and network optimization.
* **Future Potential**: Development of on-demand synthetic data generation frameworks.

## Future Developments

Cortensor plans to enhance its gamification and quality control features:

* Advanced PoUW algorithms for more diverse AI tasks.
* Integration of federated learning principles into the validation process.
* Expansion of synthetic data generation capabilities for specific industry applications.


# Incentive Structure

Cortensor's incentive structure is designed to encourage participation, ensure network reliability, and reward high-quality contributions. This multi-tiered system aligns the interests of node operators, validators, and users, creating a robust and efficient decentralized AI inference network.

### Token-Based Rewards

Cortensor uses its native token, $COR, to incentivize various activities within the network:

**1. Network Incentives**

* **Proof of Inference (PoI) & Proof of Useful Work (PoUW)**: Nodes earn $COR tokens by participating in network validation tasks. These tasks are designed to assess the quality, accuracy, and usefulness of AI inference results. This ensures that nodes are consistently contributing valuable work to the network.

**2. User Payments**

* **AI Inference Tasks**: Nodes are rewarded with $COR tokens for fulfilling user requests for AI inference. The payment is based on the complexity and resource intensity of the tasks, ensuring that nodes are compensated fairly for their computational contributions.

**3. Staking Incentives**

* **Node Operator Staking**: All node operators are required to stake $COR tokens as a form of security deposit. This staking mechanism helps secure the network by ensuring that only committed operators participate. If nodes fail to meet performance or reliability standards, their staked tokens may be penalized.
* **Regular User Staking**: Regular users can stake $COR tokens to earn APR (Annual Percentage Rate) as a form of network security. This not only supports the network’s stability but also helps reduce sell pressure by incentivizing long-term token holding.

### Multi-Level Validation System

Cortensor employs a sophisticated validation system to maintain high standards across the network:

**1. Router Nodes**

* **Task Allocation**: Router nodes assign AI tasks to appropriate inference nodes and conduct initial result validation. They earn rewards for efficient task distribution and preliminary validations.

**2. Guard/Validation Nodes**

* **Comprehensive Validation**: These nodes perform detailed checks on inference results, scoring them for accuracy and reliability. Higher validation quality leads to increased rewards, reinforcing the importance of thorough verification.

### Reputation System

* **Performance-Based Reputation**: Node performance, accuracy, and consistency contribute to a reputation score. A higher reputation enhances a node’s opportunities for task assignments and rewards, promoting continuous improvement.

### Gamified Supply-Side Development

Cortensor's unique approach to building a robust supply side involves gamification:

**1. Level 1: Liveness and Health Checks**

* **Basic Operations**: Nodes are rewarded for maintaining consistent availability and responsiveness, ensuring a stable network foundation.

**2. Level 2: Capability Assessment**

* **Performance Evaluation**: Nodes are assessed based on speed, computational power, and reliability. Higher-performing nodes are eligible for more complex tasks and higher rewards, creating a competitive environment.

### AI Marketplace Incentives

* **Specialized Services**: Node operators can offer unique AI models or services in the Cortensor marketplace, earning additional rewards. Smart contracts manage these transactions, ensuring fair compensation for all contributors.

### Benefits of the Incentive Structure

* **Network Reliability**: Encourages consistent participation and high uptime across the network.
* **Quality Assurance**: Rewards nodes for delivering accurate, high-quality AI inference results.
* **Innovation**: Incentivizes the development and deployment of new AI models and services, driving continuous innovation.
* **Fair Compensation**: Ensures that contributors are rewarded proportionally to their efforts and resources, promoting fairness.
* **Scalability**: Attracts a diverse and growing participant base, enhancing the network's capabilities over time.

### Future Developments

Cortensor is committed to refining its incentive structure based on real-world performance and community feedback. Potential enhancements include:

* **Dynamic Reward Adjustments**: Adaptation of rewards based on network demand, resource availability, and task complexity.
* **Specialized Incentives**: Introduction of incentives for niche AI tasks or industry-specific applications, encouraging specialized contributions.
* **DeFi Integration**: Exploring integration with DeFi protocols to offer additional yield opportunities for $COR token holders.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Universal AI Accessibility

Cortensor is designed to democratize access to advanced AI inference capabilities, bridging the gap between traditional web services and blockchain technologies. This universal accessibility ensures that a wide range of users and applications can leverage Cortensor's decentralized AI infrastructure.

## Cross-Platform Compatibility

**Web2 Integration**

* REST API support for seamless integration with traditional web applications.
* Compatible with existing AI frameworks, including OpenAI's interfaces.
* Enables easy migration for developers familiar with centralized AI services.

**Web3 Capabilities**

* Native Web3 SDK for blockchain-based applications.
* Smart contract integration for decentralized applications (DApps).
* Token-based access and incentive mechanisms.

## Flexible Development Options

**OpenAI Compatibility**

* API endpoints mirroring OpenAI's structure for easy adoption.
* Minimal code changes required when migrating from centralized AI services.

**Customization Features**

* Support for memory and vector storage integration.
* Ability to fine-tune models for specific use cases.
* Extensible architecture allowing for custom AI model deployment.

## Cost-Effective Solutions

* Competitive pricing compared to centralized AI providers.
* Token-based economy allowing for flexible pricing models.
* Reduced infrastructure costs for developers through decentralized resources.

## Wide Range of Applications

Cortensor's universal accessibility enables diverse use cases across industries:

* **Healthcare**: Secure and privacy-preserving medical data analysis.
* **Finance**: Decentralized fraud detection and risk assessment.
* **Education**: Personalized learning experiences and content generation.
* **Creative Industries**: AI-assisted content creation and editing.
* **IoT and Edge Computing**: Efficient AI inference for resource-constrained devices.

## Developer-Friendly Features

* Comprehensive documentation and tutorials.
* SDKs in multiple programming languages.
* Community-driven support and resources.
* Regular updates and feature additions based on developer feedback.

## Privacy and Security

* Option for encrypted data transmission and storage.
* Customizable privacy settings through L3 chains.
* Compliance with data protection regulations through flexible architecture.

## Future Developments

Cortensor is committed to expanding its universal accessibility features:

* Integration with additional AI frameworks and models.
* Enhanced interoperability with emerging Web3 standards.
* Development of industry-specific AI solutions and templates.

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Multi-layer Blockchain Architecture

Cortensor employs a sophisticated multi-layer blockchain architecture to ensure security, scalability, and flexibility in its decentralized AI inference network. This approach allows for efficient data management, secure orchestration of AI tasks, and adaptable privacy features.

### Layer Structure

1. **Layer 1 (L1): Base Layer**
   * Purpose: Ensures the fundamental integrity and security of the network.
   * Features: Consensus mechanism, basic transaction processing, network-wide state management.
2. **Layer 2 (L2): AI Orchestration Layer**
   * Purpose: Manages AI inference requests, results, and associated data.
   * Features: Smart contracts for AI task allocation, incentive distribution mechanisms, data storage for inference results, marketplace for AI models.
3. **Layer 3 (L3): Privacy and Customization Layer**
   * Purpose: Offers privacy-preserving computations and specialized services.
   * Features: Encrypted prompts and completions, permissioned access for sensitive data, customizable chains for specific use cases or enterprises.

### Chains for AI Orchestration

* **L2 Chain**: Acts as the main orchestration layer, managing task distribution, node reputation, and basic data storage.
* **L3 Chains**: Provide additional privacy and customization options, allowing for encrypted operations and specialized AI services.

### Managing AI Inference and Orchestration Data

* Secure data management across layers, with options for public (L2) and private (L3) storage.
* Efficient handling of inference requests, results, and associated metadata.
* Support for vector storage and other AI-specific data structures.

### Incentivization and Validation Processes

* Token-based rewards for node operators, validators, and contributors.
* Multi-level validation system:
  1. Router nodes for task assignment and initial validation.
  2. Guard/validation nodes for result verification and scoring.
  3. Reputation system based on node performance and result accuracy.

### AI Marketplace

* Facilitated by the L2 chain, allowing for the exchange of AI models and services.
* Smart contracts govern marketplace transactions and ensure fair compensation.
* Integration with the incentive structure to reward high-quality contributions.

### Key Benefits of Multi-Layer Architecture

1. **Scalability**: Distributes computational load across layers, allowing for greater transaction throughput.
2. **Flexibility**: Enables the addition of new features and services without disrupting the base layer.
3. **Privacy Options**: Provides varying levels of privacy, from public transactions to fully encrypted operations.
4. **Customization**: Allows for the creation of specialized L3 chains tailored to specific industry needs or privacy requirements.

### How It Works

1. **Base Transactions**: Fundamental network operations occur on L1.
2. **AI Task Orchestration**: L2 manages the assignment of AI inference tasks to appropriate nodes.
3. **Data Management**: L2 stores and manages inference data, with options for more secure storage on L3.
4. **Privacy-Enhanced Operations**: Sensitive computations or data can be processed on L3 chains with restricted access.

### Future Developments

Cortensor plans to expand its multi-layer architecture to support:

* Advanced cross-layer optimizations for improved performance
* Integration with other blockchain networks for enhanced interoperability
* Development of industry-specific L3 solutions

***

**Disclaimer:** This page and the associated documents are currently a work in progress. The information provided may not be up to date and is subject to change at any time.


# Technical Architecture

Cortensor's architecture is meticulously crafted to provide a robust, scalable, and secure platform for decentralized AI inference. Our technical implementation integrates cutting-edge blockchain technology with advanced AI capabilities, establishing a unique ecosystem for AI computation and orchestration. Here is an overview of the key components and functionalities that define the Cortensor architecture:

## **Key Components**

1. **Multi-Layer Blockchain Architecture**:
   * **Layer 1 (L1)**: The foundational layer that ensures fundamental security and consensus.
   * **Layer 2 (L2)**: Dedicated to AI orchestration and task management.
   * **Layer 3 (L3)**: Focuses on privacy-preserving computations and supports customized chains.
2. **Proof of Useful Work (PoUW)**:
   * A novel consensus mechanism that combines network security with practical AI tasks.
   * Implements a two-level system for node evaluation and capability assessment.
3. **Decentralized AI Inference**:
   * Utilizes a distributed network of nodes to perform AI computations.
   * Supports various hardware types, including CPUs and GPUs, ensuring inclusivity and adaptability.
4. **Intelligent Routing System**:
   * Router nodes are employed for optimal task allocation.
   * Dynamic matching of inference requests to node capabilities ensures efficient task execution.
5. **Multi-Layered Validation**:
   * Guard/validation nodes verify the results of AI tasks.
   * A reputation system ensures high-quality outputs by evaluating node performance.
6. **Universal Accessibility**:
   * Compatible with both Web2 (REST API) and Web3 (SDK) environments.
   * Integrates seamlessly with popular AI frameworks and models.
7. **Privacy and Security Features**:
   * Provides optional encrypted data transmission and storage.
   * L3 chains offer permissioned access and enhanced privacy for sensitive computations.

### **Core Functionalities**

* **AI Inference Task Distribution and Execution**: Efficiently distributes and executes AI inference tasks across the network.
* **Node Capability Assessment and Ranking**: Periodically assesses and ranks nodes based on their capabilities and performance.
* **Token-Based Incentive System**: Rewards nodes for their contributions to AI inference and task execution.
* **AI Model Marketplace**: Facilitates the sharing, monetization, and access to various AI models.
* **Synthetic Data Generation**: Supports the generation of synthetic data for various applications, enhancing data diversity and availability.

### Roles

Cortensor's network consists of various node types, each playing a specific role in the ecosystem:

* **Router Nodes**: Act as intermediaries between users and miners, ensuring secure communication and optimal task allocation.
* **Miner Nodes**: Perform AI inferencing tasks, ranging from low-end devices to high-end GPUs, contributing to the network's computing power.
* **Client/Users**: Initiate sessions, submit prompts, and receive AI inference results through the network.
* **Oracle/Master Guard Nodes**: Maintain block time consistency, validate tasks, and ensure network reliability.

### Network & Flow

The network's flow is designed to facilitate seamless interaction between different nodes and ensure efficient task execution:

* **Session Creation**: Users create sessions by depositing tokens, which are calculated in terms of LLM tokens.
* **Task Routing**: Router nodes handle the incoming prompts, verify payments, and route tasks to the appropriate miner nodes.
* **Task Execution**: Miner nodes perform the assigned tasks and submit results securely.
* **Validation**: Results are validated by other miner nodes or validation nodes to ensure accuracy and reliability.

### Coordination & Orchestration

Effective coordination and orchestration are crucial for maintaining the network's performance and reliability:

* **Job Scheduling**: Router nodes act as job schedulers, allocating tasks based on node capabilities and user requirements.
* **Dynamic Matching**: Ensures that tasks are matched to the most suitable nodes, optimizing resource utilization and task completion times.

### AI Inference

#### **Open Source Models**

* Utilizes open-source AI models to provide a wide range of inferencing capabilities.
* Ensures compatibility and integration with various AI frameworks.

**Performance and Scalability**

* Designed to handle a large number of concurrent tasks.
* Scales efficiently with the addition of more nodes, ensuring robust performance even under high demand.

#### Consensus & Validation

* **Proof of Inference**: A consensus mechanism that ensures tasks are completed correctly and efficiently.
* **Validation Process**: Involves multiple nodes in the validation process to ensure accuracy and reliability.

### Data Management

* **Data Privacy**: Ensures data is handled securely and privately, with optional encryption.
* **Data Storage**: Utilizes decentralized storage solutions to maintain data integrity and accessibility.

### Security & Privacy

* **Encrypted Transmission**: Ensures all communications within the network are encrypted.
* **Permissioned Access**: L3 chains provide enhanced privacy for sensitive computations.

### Type of Services

* **AI Inference**: Provides real-time AI inferencing capabilities.
* **Synthetic Data Generation**: Supports the generation of synthetic data for various applications.
* **AI Model Marketplace**: A platform for sharing and monetizing AI models.

### Community & Ecosystem

**Contributing to Cortensor**

* Encourages developers and AI enthusiasts to contribute to the network.
* Provides incentives and rewards for valuable contributions.

**Incentives & Rewards**

* **Token-Based Rewards**: Nodes are rewarded with tokens for their contributions to the network.
* **Staking**: Nodes stake tokens to participate in the network, ensuring commitment and reliability.

**Governance & Compliance**

* **Decentralized Governance**: Ensures the network is governed by its community, promoting transparency and fairness.
* **Compliance**: Adheres to relevant regulations and standards to ensure legal compliance.

**Tokenomics**

* **Token Distribution**: Tokens are distributed based on contributions and participation.
* **Utility**: Tokens are used for various transactions within the network, including paying for services and rewarding nodes.

This comprehensive overview of Cortensor's technical architecture outlines the foundational elements that make it a pioneering platform for decentralized AI inference. The detailed components and functionalities ensure that Cortensor remains robust, scalable, and secure, fostering a collaborative and inclusive ecosystem for AI innovation.


# Design Principles

### Keeping It Simple and Effective

At Cortensor, we embrace simplicity as a core design principle, guided by Albert Einstein's wisdom:&#x20;

> *"Make things as simple as possible, but not simpler."* - Albert Einstein

Our approach ensures a maintainable, scalable, and efficient system through three fundamental principles:

#### 1. KISS (Keep It Simple, Stupid)

* **Simple Design**: We focus on essential features, avoiding unnecessary complexity.
* **Ease of Maintenance**: Simplicity makes our system easier to understand and maintain.

> "Debugging is twice as hard as writing the code in the first place." - Brian Kernighan

#### 2. YAGNI (You Aren't Gonna Need It)

* **Avoid Premature Features**: We implement functionality only when it's truly needed.
* **Timely Decision-Making**: Our design choices are based on current requirements, not speculative needs.

#### 3. Occam's Razor

* **Minimal Assumptions**: We design solutions with the fewest assumptions to ensure robustness.
* **Efficiency**: Our focus is on straightforward problem-solving, avoiding unnecessary layers and complexity.

#### Balancing Simplicity and Functionality

While prioritizing simplicity, we carefully balance it with essential functionality:

* **Avoiding Complexity**: We actively prevent feature creep and over-engineering.
* **Future-Proofing**: Our designs consider maintainability, extensibility, and reusability.

#### Practical Application

Here's how we apply these principles in Cortensor:

1. **Modular Architecture**: Enables easy updates and scalability.
2. **Streamlined Codebase**: Focuses on core functionalities, enhancing performance and reliability.
3. **Intuitive User Interface**: Ensures ease of use for both developers and end-users.
4. **Efficient Resource Utilization**: Optimizes network and computational resources.

#### Conclusion

By adhering to KISS, YAGNI, and Occam's Razor, Cortensor maintains a lean, efficient, and scalable platform. This approach not only ensures current effectiveness but also facilitates future growth and adaptability in the rapidly evolving field of decentralized AI inference.


# AI Inference

#### AI Inference

AI inference within the Cortensor network is at the core of the platform’s capabilities, enabling efficient and scalable AI computations through a decentralized architecture. This section delves into the mechanisms and processes that facilitate AI inference, ensuring high performance, inclusivity, and security.

**Overview**

Cortensor's AI inference leverages a distributed network of miner nodes to perform computations using advanced AI models. The system supports a diverse range of hardware, from low-end devices to high-end GPUs, ensuring broad participation and inclusivity. The primary AI models currently supported include Llama 3, available in both quantized and regular versions, allowing even lower-end devices to contribute effectively.

**AI Inference Process**

**Task Initiation**:

* Users create sessions and submit prompts through router nodes.
* Router nodes verify session parameters, including payment and model specifications, before processing the request.

**Task Allocation**:

* Router nodes dynamically allocate inference tasks to suitable miner nodes.
* Allocation algorithms consider node performance, current workload, and specific task requirements to optimize resource utilization.

**Inference Execution**:

* Miner nodes perform the assigned AI inference tasks.
* Tasks are segmented into smaller subtasks to enhance processing efficiency and balance the workload.
* Model quantization allows lower-end devices to handle inference tasks, promoting inclusivity.

**Result Submission**:

* Miner nodes submit the results securely through encrypted channels.
* Results are sent to the router nodes for initial aggregation and verification.

**Validation**:

* Validation nodes or other miner nodes verify the inference results.
* Validation methods include semantic checks, embedding comparisons, and checksum verifications.
* Users can configure the level of validation required, balancing between cost and accuracy.

**Result Delivery**:

* Validated results are delivered to users through their preferred channels.
* The router node ensures secure and efficient result delivery while maintaining user privacy.

**Security and Privacy**

**Encrypted Communication**:

* All communications within the network are encrypted to ensure data privacy and integrity.
* Router nodes manage encryption and decryption, ensuring secure interactions between clients and miner nodes.

**Validation and Verification**:

* Validation nodes verify the accuracy of AI inference results.
* Configurable validation processes allow users to specify the required level of accuracy, influencing costs and ensuring reliable outputs.

**Inclusivity through Quantization**

**Model Quantization**:

* Cortensor employs model quantization to support a diverse range of hardware, including lower-end devices.
* This inclusivity allows devices with limited computational power to perform inference tasks, enhancing the network's scalability and resource utilization.
* The focus on supporting Llama 3 models, both quantized and regular, ensures wide participation and efficient task execution across different hardware capabilities.


# Open Source Models

Cortensor leverages open-source models to provide robust and flexible AI inference capabilities. By utilizing these models, Cortensor ensures that the network remains accessible, transparent, and adaptable to various use cases.

## **Supported Models**

### **Llama 3**:

* Available in both quantized and regular versions.
* Supports a wide range of hardware, from low-end devices to high-end GPUs.
* Enables broad participation in AI inference tasks by accommodating diverse computational resources.
* Quantization allows lower-end devices to perform inference tasks, promoting inclusivity and scalability.

**Future Plans**

* **Expansion of Llama 3 Models**: Cortensor plans to add more variations of Llama 3-based models to enhance the network’s capabilities and provide greater flexibility for different tasks.
* **Integration of Additional Open Source Models**: Beyond Llama 3, Cortensor is committed to integrating other open-source AI models. This will further diversify the network’s capabilities and ensure it remains at the forefront of AI technology.

**Benefits of Open Source Models**

* **Transparency**: Open-source models allow for greater transparency and trust within the network, as their development and updates are publicly available.
* **Community-Driven Innovation**: Leveraging open-source models encourages community contributions and collaboration, driving continuous improvement and innovation.
* **Cost-Effectiveness**: Open-source models reduce the cost barriers for implementing advanced AI capabilities, making AI inference more accessible to a broader audience.
* **Flexibility**: The use of open-source models ensures that Cortensor can adapt to new advancements and integrate various AI technologies as they evolve.
* **Quantization**: Model quantization enables lower-end devices to participate in AI inferencing, enhancing the network’s inclusivity and resource utilization.


# Centralized vs Decentralized Models

The shift from centralized to decentralized AI models is critical to fostering trust, fairness, and resilience in AI workflows. While centralized systems have been the traditional standard, their limitations highlight the need for decentralized alternatives like Cortensor. Below, we explore the key differences and how Cortensor addresses the challenges of centralized AI.

***

## **Challenges of Centralized AI Models**

1. **Single Points of Failure**
   * Centralized systems rely on a single provider, which can lead to catastrophic failures in case of outages, technical errors, or cyberattacks.
   * This reliance increases vulnerability, making the system less robust and scalable.
2. **Bias Risks**
   * Centralized control allows for biases in training data, algorithms, and inference outputs.
   * Lack of transparency raises concerns about fairness and accountability, especially in critical applications like healthcare, finance, and legal systems.

***

## **How Cortensor Solves These Challenges**

1. **Decentralized Validation with PoUW**
   * **Proof of Useful Work (PoUW)** ensures task relevance and quality through a decentralized validation process.
   * Tasks are distributed across multiple miners, and their outputs are validated collaboratively to guarantee meaningful results.
2. **Cross-Validation with PoI**
   * **Proof of Inference (PoI)** eliminates bias and ensures reliability by cross-validating outputs from multiple nodes.
   * This process prevents tampering or manipulation by any single entity and ensures consistent results.
3. **Redundancy and Resilience**
   * By leveraging a decentralized architecture, Cortensor eliminates reliance on a single provider.
   * Multiple nodes working in parallel enhance the system’s resilience and scalability, reducing the risk of disruptions.

***

## **Benefits of Decentralized AI with Cortensor**

* **Trustworthy AI Outputs**: Decentralized validation mechanisms like PoI ensure outputs are unbiased and reliable.
* **Fairness in AI**: By distributing control across nodes, Cortensor prevents monopolization and promotes equitable participation.
* **Enhanced Security**: Decentralized systems are inherently more secure against single-point failures and attacks.
* **Scalability**: Decentralized task allocation and processing allow the network to scale efficiently as demand grows.

***

## **Cortensor’s Gold Standard for Decentralized AI**

Cortensor's innovative architecture redefines the AI landscape by addressing the inherent flaws of centralized systems. Its dual validation mechanisms, **PoUW** and **PoI**, ensure that every task processed through the network is meaningful, unbiased, and high-quality.

By removing reliance on centralized providers, Cortensor empowers developers, businesses, and communities to trust and build upon a resilient, fair, and scalable AI framework—setting the gold standard for decentralized AI innovation.


# Quantization

Cortensor employs LLM (Large Language Model) quantization to adapt to a wide range of hardware devices, from low-end CPUs to high-end GPUs. Quantization is a process that reduces the precision of the model’s parameters, allowing the model to run efficiently on less powerful hardware without significantly compromising accuracy. This capability is crucial for democratizing AI inference, enabling broader accessibility, and ensuring that AI-powered applications can operate on diverse devices.

### **What is LLM Quantization?**

LLM quantization is the process of converting a model's parameters, typically stored in high precision (e.g., 32-bit floating-point), into lower precision formats (e.g., 8-bit integers). This reduction in precision significantly decreases the model's size and computational requirements, making it possible to run complex AI models on devices with limited computational power.

### **Why is LLM Quantization Useful?**

Quantization is especially useful in scenarios where AI inference tasks do not require real-time processing or extremely high precision. By enabling models to run on a variety of devices, quantization allows Cortensor to support a more inclusive and adaptive AI ecosystem. Here’s why it’s important:

1. **Adaptation Across Hardware**:
   * **Low-End CPUs**: Can handle basic AI tasks such as text classification, simple content generation, or basic data sorting.
   * **High-End GPUs**: For miners using high-end GPUs who choose not to use quantization, their devices will be assigned to tasks requiring high accuracy and quality outputs. If high-end devices do utilize quantization, they can process tasks much faster, serving more user requests, albeit with lower precision and accuracy. This flexibility ensures that precision-critical applications, such as detailed chatbot responses or knowledge retrieval, are handled by the most capable hardware when needed.
2. **Cost-Effective AI Solutions**:
   * By offloading less critical tasks to lower-end devices, Cortensor can offer more cost-effective AI services. This approach lowers the barrier to entry for AI-enabled applications and makes advanced AI capabilities accessible to a broader audience.
3. **Broad Use Cases**:
   * **Text Classification**: Basic categorization tasks can be performed on lower-end devices.
   * **Content Generation**: Non-time-sensitive content creation tasks can be distributed across a variety of hardware.
   * **Predictive Analytics**: For tasks where near-instantaneous results are not required, quantized models can provide efficient and effective solutions.

### **Cortensor's Approach to Quantization**

Cortensor’s network takes full advantage of LLM quantization by regularly testing and classifying the capabilities of each device through its gamified quality control processes, namely Proof of Inference (PoI) and Proof of Useful Work (PoUW). These processes help categorize devices into low-end and high-end tiers, with or without using quantization. By continuously assessing device performance, the network can dynamically allocate tasks to the most suitable hardware, ensuring both efficiency and cost-effectiveness. For miners with high-end GPUs who opt not to use quantization, their hardware will be prioritized for high-accuracy tasks, while those using quantization can serve a larger volume of requests more quickly, though with slightly reduced precision.

#### **User Flexibility in Service Subscription**

Cortensor also provides flexibility for users during service subscription. Users can choose whether to prioritize cost-effectiveness with quantized models or opt for higher accuracy by selecting services that utilize non-quantized models on high-end GPUs. This allows users to tailor their AI inference services to their specific needs, whether they require rapid responses or the highest possible accuracy.

### **Conclusion**

LLM quantization is a pivotal component of Cortensor’s strategy to build an inclusive and adaptive AI ecosystem. By enabling AI inference on a wide range of devices, from basic CPUs to advanced GPUs, Cortensor ensures that AI technology is accessible, scalable, and cost-effective. This flexibility, combined with Cortensor's robust quality control processes, supports a diverse array of AI applications and use cases, driving the broader adoption of AI in everyday applications. Whether through quantized models on lower-end devices or high-precision outputs on top-tier hardware, Cortensor provides tailored solutions to meet the varied needs of its users and miners.


# Performance and Scalability

Cortensor's architecture is designed to deliver high performance and scalability for AI inference tasks. This section highlights the mechanisms and strategies employed to ensure the network can efficiently handle increasing workloads and maintain robust performance.

### **Key Strategies**

**Dynamic Task Allocation**:

* Router nodes dynamically allocate tasks to miner nodes based on real-time assessments of node capabilities and current workloads.
* This ensures optimal resource utilization and minimizes processing delays.

**Task Segmentation**:

* Complex AI inference tasks are segmented into smaller subtasks.
* These subtasks are distributed across multiple miner nodes, ensuring balanced workload distribution and faster task completion.

**Model Quantization**:

* Utilizes quantized versions of AI models like Llama 3.
* Enables lower-end devices to participate in AI inferencing, enhancing overall network capacity and performance.

**Scalable Infrastructure**:

* Supports a diverse range of hardware, from low-end devices to high-end GPUs.
* Easily scales with the addition of new nodes, maintaining efficient performance even as demand increases.

**Load Balancing**:

* Implements advanced load balancing techniques to distribute tasks evenly across the network.
* Prevents bottlenecks and ensures that no single node is overwhelmed with too many tasks.

### **Performance Metrics**

**Latency and Throughput**:

* Monitors latency and throughput to ensure timely processing of AI inference tasks.
* Adjusts task allocation dynamically to maintain low latency and high throughput.

**Resource Utilization**:

* Continuously assesses resource utilization across the network.
* Optimizes the use of available computational power to enhance performance.

**Reliability and Uptime**:

* Ensures high reliability and uptime through robust validation and verification processes.
* Implements fault-tolerant mechanisms to handle node failures without impacting overall performance.

### **Future Enhancements**

* **Adaptive Scaling**: Introduce adaptive scaling techniques to automatically adjust the network capacity based on real-time demand.
* **Advanced Load Balancing**: Develop more sophisticated load balancing algorithms to further optimize task distribution and performance.
* **Enhanced Monitoring**: Implement advanced monitoring tools to provide real-time insights into network performance and resource utilization.


# LLM Memory

LLM Memory vs RAG - and the Role of Cortensor’s Router Node

### **1. Distinction Between RAG and Memory**

Retrieval-Augmented Generation (RAG) is designed to serve static or semi-structured knowledge bases (e.g., articles, documentation, search indices). It works well for surfacing known facts and summaries but does not evolve dynamically with user interaction.

In contrast, *memory* in LLM systems refers to per-user, per-session ephemeral state. It includes user actions, conversation history, task outcomes, and session-specific details. Memory evolves in real-time and is scoped to individual users or sessions — making it fundamentally different from RAG.

### **2. Memory Should Not Be Global**

LLM memory is inherently **contextual** and **localized**. Sharing it across users or agents introduces semantic errors and privacy risks. For instance, a failure message specific to User A has no relevance or utility for User B.

Memory must be:

* Scoped to a user-agent pair
* Ephemeral and session-bound
* Non-generalizable, unlike RAG

This requires localized storage and injection mechanisms that are distinct from global, static retrieval systems.

### **3. Cortensor Router Node as Memory Engine**

Cortensor’s Router Nodes already act as the coordination hub between users and miner nodes. This positions them naturally to:

* Store session/user-specific memory in fast-access databases (e.g., Redis)
* Inject structured memory blocks (e.g., `<FACTS>`) into prompts sent to inference agents
* Manage memory lifecycle and cleanup post-session
* Apply memory to prompts dynamically, enhancing personalization and context continuity

### **4. Lightweight & Deterministic Implementation**

Router Nodes handle RESTful coordination and task metadata routing. Adding memory support here introduces minimal architectural complexity. Because memory is:

* Local (per node, not globally shared)
* Deterministic (based on clear session/user boundaries)
* Stateless across nodes (no need for distributed sync)

It can be implemented as a simple middleware service tightly coupled with Router logic.

### **5. Economic Utility in Agent-Based Systems**

Cortensor aligns memory with economic outcomes:

* Injecting session memory improves prompt relevance and completion quality
* Reduces token waste and incorrect predictions
* Enhances agent performance per inference
* Supports session-aware agent behavior (e.g., retry logic, progressive reasoning)

This turns Router Nodes into **personalized agent gateways**, not just routers — responsible for memory-aware AI execution.

### **6. Future RAG from Memory (Optional, Async)**

While short-term memory enhances real-time inference, longer-term summaries (e.g., common issues, usage patterns) can be distilled asynchronously into RAG-like datasets. This should not interfere with the real-time session memory lifecycle.

***

Cortensor Router Nodes are not just routers - they are strategically positioned to become **memory injection engines** for decentralized AI systems.

This enables:

* Personalized, session-based inference
* Better agent output quality
* Economic alignment with utility-driven tasks
* Minimal infrastructure overhead

Memory, like compute, should flow to where it makes sense - and in Cortensor, that means the Router Node.


# CPU Instruction Sets for LLM Inference: AVX, AMX, SME vs GPUs

### 1. Introduction

Large Language Models (LLMs) have historically been deployed on **GPUs** due to their high throughput for dense linear algebra operations. However, **supply constraints, energy consumption, and cost per token** have pushed both industry and research communities to revisit CPUs as viable inference engines — particularly when augmented with new instruction sets like **AVX (Advanced Vector Extensions), AMX (Advanced Matrix Extensions), and SME (Scalable Matrix Extension)**.

These ISA (Instruction Set Architecture) extensions provide specialized matrix/vector operations that map directly to transformer workloads, especially post-quantization. As a result, CPUs are gaining renewed interest as **scalable, energy-efficient alternatives** for small-to-medium model inference, pre/post-processing, and even some server-side LLM workloads.

***

### 2. The Instruction Sets

#### **AVX / AVX-512 (Intel & AMD, x86)**

* SIMD (vector) extensions, widening registers to accelerate dot-products and vector operations.
* **AVX-512 VNNI** and **BF16** instructions target INT8 and BF16 workloads directly.
* **Adoption:** Present in Intel Xeon Scalable, AMD EPYC Zen 4/5. Widely used in `llama.cpp`, `llamafile`, Hugging Face Optimum CPU kernels.
* **Role:** Boosts throughput for quantized matmuls, attention blocks, and pre/post-processing.

***

#### **AMX (Intel Advanced Matrix Extensions, x86)**

* Tile-based matrix multipliers built into **Intel 4th Gen Xeon (Sapphire Rapids)** and beyond (Granite Rapids / Xeon 6).
* Optimized for **INT8 and BF16** matmuls (core of transformer workloads).
* **Software:** Integrated in **oneDNN**, **PyTorch (via mkldnn backend)**, and **OpenVINO**.
* **Adoption:** Intel, AWS EC2 m7i/m7i-flex instances; enterprise inference stacks.
* **Role:** Reduces latency & boosts throughput on quantized LLMs running on Xeon.

***

#### **SME / SME2 (Arm Scalable Matrix Extensions, Armv9.x)**

* Arm’s equivalent of AMX: **tile-style matrix ISA**, augmenting SVE/SVE2.
* **SME2 (Armv9.3)** refines memory and vectorization for transformer ops.
* **Software:** Enablement via **KleidiAI**, **ONNX Runtime**, Android integration announced (2025).
* **Adoption:** Emerging in Armv9 client CPUs (e.g., Apple M4, mobile SoCs) and **AWS Graviton4** (Armv9 SVE; SME2 soon).
* **Role:** Brings competitive perf/Watt for inference on **cloud Arm servers** and **on-device AI**.

***

### 3. Why CPUs Matter for LLM Inference

1. **Availability & Cost**\
   CPUs are abundant, cheaper, and not subject to GPU shortages.
2. **Perf/Watt Efficiency**\
   Modern Xeon/EPYC cores with AMX/AVX-512 run quantized models at **lower joules/token** compared to GPUs at small batch sizes.
3. **Memory Access**\
   CPUs can leverage larger system memory, useful for models with large parameter footprints or long context windows.
4. **Software Ecosystem**\
   Major frameworks (PyTorch, ONNX Runtime, OpenVINO) now map automatically to AVX/AMX/SME backends.
5. **Quantization Synergy**\
   The industry trend toward **INT8 / BF16 / 4-bit quantization** aligns perfectly with AMX and SME instructions.

***

### 4. Current Adoption & Industry Players

* **Intel**: AMX is shipping in Xeon Scalable (Sapphire/Granite Rapids). Integrated into PyTorch (via oneDNN) and OpenVINO. Benchmarks published for LLaMA-2/3.
* **AMD**: AVX-512 + VNNI + BF16 in Zen 4/5 EPYC. `llama.cpp` optimized paths show **tokens/sec boosts** vs AVX2. AMD positions EPYC as **GPU-light inference solution**.
* **Arm**: SME2 announced with Armv9.3, Android integration in 2025, and cloud adoption (Graviton4). Apple M4 benchmarks show strong uplift in FP32 matmuls.
* **Cloud Providers**:
  * **AWS Graviton4**: SVE/BF16/INT8; SME2 support in roadmap.
  * **Azure & GCP**: Xeon AMX instances available for LLM workloads.

***

### 5. Benchmarks & Comparisons

#### **CPU Benchmarks with AMX / AVX**

* **OpenMetal (Xeon AMX)**:
  * LLaMA-3 3.2B INT8 → \~57 tokens/sec (AMX on) vs \~28 t/s (AMX off).
  * With 4-bit quantization → \~80 t/s possible.
* **Presidio (AWS m7i with Xeon AMX)**:
  * Generic prompts: \~100 t/s with AMX vs \~25 t/s baseline.
  * RAG prompts: \~120 t/s with AMX vs \~35–40 t/s without.
* **llama.cpp on AMD EPYC AVX-512**:
  * Significant uplift vs AVX2; practical for local/agent workloads.

***

#### **Arm SME / SME2**

* **Apple M4 (SME microbenchmarks)**:
  * > 2.3 TFLOPS FP32 matmul throughput.
  * Outperforms vendor BLAS for small matrix ops.
* **Arm Lumex CSS (SME2 reference)**:
  * Up to **5× AI perf uplift** vs prior gen CPUs.
  * 4.7× lower latency in speech workloads.

***

#### **CPU vs GPU Gap**

* **Small Models (\~3B, quantized)**:
  * CPU AMX → \~50–100 t/s.
  * GPU (A100/H100) → 1000+ t/s.
  * Gap: \~10×.
* **Medium Models (\~20–70B)**:
  * CPU → tens of t/s.
  * GPU → hundreds–thousands t/s.
  * Gap: **5–30×** depending on precision & batch.
* **First Token Latency**:
  * CPU AMX: \~100–200ms.
  * GPU: \~10–50ms.
* **Perf/Watt / Cost**:
  * CPU competitive at small batch sizes & intermittent workloads.
  * GPU wins at scale & high concurrency.

***

### 6. Future Outlook

* **AMX** will dominate Intel’s CPU inference story, aligned with **INT8/BF16 quantization** and software ecosystem (PyTorch, OpenVINO).
* **AVX-512** will remain a strong optimization path on AMD EPYC and Intel consumer CPUs, especially for lightweight inference (agents, RAG pipelines).
* **SME2** positions Arm for on-device AI and eventually cloud-scale LLM inference as Neoverse V3/V4 cores adopt it.
* **GPU vs CPU roles will bifurcate**:
  * **GPUs**: High throughput, very large models, training & dense inference.
  * **CPUs**: Quantized mid-tier inference, tokenization, edge, cost-sensitive serving.
  * **NPUs / accelerators**: May bridge gaps, but CPUs offer universal deployment.

***

### 7. Key Takeaways

1. **AMX and SME2 are the future of CPU inference.** They bring GPU-like matmul performance into CPUs, tightly aligned with quantization trends.
2. **Big corps already betting:** Intel (AMX), AMD (AVX-512), Arm (SME2), AWS (Graviton4), Apple (M4 SME).
3. **Benchmark reality:** GPUs are still 5–30× faster for large LLMs, but CPUs can be cost-competitive for small-to-mid models.
4. **Practical today:** Use **Xeon AMX / EPYC AVX-512** for mid-tier workloads (3–20B LLMs) with INT8/4-bit quantization.
5. **Emerging tomorrow:** Arm SME2 for **on-device & cloud** AI; watch ecosystem enablement via ONNX Runtime and Android.

***

### 8. Suggested Next Steps (if applying to Cortensor / similar infra)

* Implement **ISA-aware scheduling** in your router (AVX2 vs AVX-512 vs AMX vs SME).
* Benchmark **INT8 vs 4-bit quantization** across CPU/GPU backends for your target models (3B, 7B, 13B, 70B).
* Deploy **Xeon AMX / EPYC AVX-512 nodes** in your NodePool for cost-sensitive inference; route massive jobs to GPUs.
* Track **Arm SME2 adoption** for mobile/edge nodes (important for global decentralization).

***

📌 **Bottom line:**

* **AMX (Intel) and SME2 (Arm)** are not GPU killers but **GPU complements**.
* They’ll **extend LLM inference beyond GPUs**, making **CPU inference practical, scalable, and cost-efficient** for a significant share of workloads.


# Performance & Benchmark

Here’s a summary of relevant publicly available benchmarks relating to AMX/AVX and comparisons with GPUs.

| Source                                                                                             | Hardware / Setup                                                                   | Model / Precision / Quantization                                                                                                    | Key Results (CPU / AMX / GPU)                                                                                                                                                                                                                                                                                                                                                                                            | Notes / Caveats                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenMetal “Intel AMX Enables High-Efficiency CPU Inference for AI Workloads”**                   | Intel Xeon 4th-/5th-gen with AMX                                                   | llama 3.2B, quantized (Q4\_K\_M or Q8\_0); also some lower bit quantization (4-bit)                                                 | With AMX: up to **\~57 tokens/sec** for 3.2B Q8\_0 / \~28 t/s without AMX. With 4-bit, up to \~80 t/s in some configs. ([OpenMetal IaaS](https://openmetal.io/resources/blog/intel-amx-ai-inference-performance/?utm_source=chatgpt.com))                                                                                                                                                                                | These are modest-size models; outputs vs inputs size, batch sizes etc matter. The latency to first token is also worse relative to GPUs. This is “inference on CPU, quantized, AMX enabled vs disabled” rather than direct comparison to say H100 or A100.                        |
| **Presidio blog: “LLMs on Intel Xeon CPUs with Intel AMX”**                                        | AWS EC2 m7i.8xlarge (4th Gen Intel Xeon with AMX) vs AWS GPU instance (p3.2xlarge) | Using “Neural chat” type LLMs; comparing generic prompts and RAG (retrieval) prompts; with INT8 quantization on CPU + AMX           | For generic prompts: CPU+AMX achieved \~100 t/s (tokens/sec), vs maybe \~25-27 t/s without AMX. For RAG prompts: CPU AMX \~120 t/s, vs \~35-40 t/s without AMX. GPU instance still has higher throughput & lower latency, but the gap is smaller for quantized/INT8 models. ([Presidio](https://www.presidio.com/blogs/llms-on-intel-xeon-cpus-with-intel-amx/?utm_source=chatgpt.com))                                  | In RAG, prompt includes large input contexts which stresses memory. Also, test sizes & prompt lengths differ; plus “first token latency” on CPU tends to be higher. Also model size here is in tens of billions or smaller (for massive 70-405B models GPUs start to excel more). |
| **AMD vs NVIDIA Inference Benchmark: Who Wins?**                                                   | MI300X / MI325X vs H100 / H200 etc.                                                | Large dense models like LLaMA3-405B; FP16 or FP8 precision in many cases; focusing on throughput under certain latency constraints. | Some results: MI300X outperforms H200 (with less optimized stack) and H100 in some “large-model, memory bound” scenarios; MI325X beats H100 & H200 in several cases. Throughputs of hundreds to \~1000 tokens/sec per GPU when latency = \~some constraint. ([SemiAnalysis](https://semianalysis.com/2025/05/23/amd-vs-nvidia-inference-benchmark-who-wins-performance-cost-per-million-tokens/?utm_source=chatgpt.com)) | This is purely GPU vs GPU; useful for understanding GPU scaling but doesn’t compare with CPU/AMX/SME.                                                                                                                                                                             |
| **Arm SME2 (Lumex CSS / C1 CPU cluster)**                                                          | SME2-enabled Armv9.3 CPUs (C1 cluster)                                             | On-device AI tasks: audio generation, speech, etc.                                                                                  | Up to **5× uplift** in AI performance over prior generation CPUs; \~2.8× faster audio generation; \~4.7× lower latency for speech workloads. ([Arm Newsroom](https://newsroom.arm.com/news/announcing-lumex-css-platform-ai-era?utm_source=chatgpt.com))                                                                                                                                                                 | These are not for huge LLM (> 10-100B) inference, they’re more “on-device / mobile / sub-flagship CPU” tasks. Not direct comparison with server GPUs. And “AI performance” is loosely defined (could be a mix of tasks simpler than full transformer decoding).                   |
| **“Hello SME! Generating Fast Matrix Multiplication Kernels Using the Scalable Matrix Extension”** | Apple M4 chip (with SME)                                                           | Microbenchmarks of small matrix multiplications; FP32 (and maybe fixed-point)                                                       | SME on M4 achieved over **2.3 FP32 TFLOPS** for certain matrix sizes; SME kernels beat vendor BLAS implementations for small matrix sizes in most tested configurations. ([arXiv](https://arxiv.org/abs/2409.18779?utm_source=chatgpt.com))                                                                                                                                                                              | Microbenchmarks with small matrices are good indicators for matmul / attention building blocks, but they don’t fully reflect whole model inference (which also includes softmax, layernorm, tokenization etc.). Also, precision matters: FP32 vs quantized / INT8 / BF16 etc.     |

***

### Comparing CPU (AMX / AVX) vs GPU — Magnitude of Gaps

Putting together what’s known:

* For **small-to-medium sized models** (say \~1-10B parameters), with quantization (INT8 / lower bits) and on CPUs with AMX/AVX, token throughput can reach tens to low hundreds of tokens/sec. GPUs of course do thousands of tokens/sec in those same models.
* From Presidio: CPU with AMX + INT8 got \~100 t/s (generic prompts) vs maybe what a GPU instance could do (depending on which) — but the GPU was still faster and lower latency. ([Presidio](https://www.presidio.com/blogs/llms-on-intel-xeon-cpus-with-intel-amx/?utm_source=chatgpt.com))
* In the OpenMetal case, enabling AMX roughly doubles throughput vs without. So the CPU “wins” in that optimization sense, but it doesn’t close the gap to high-end GPUs for large models. ([OpenMetal IaaS](https://openmetal.io/resources/blog/intel-amx-ai-inference-performance/?utm_source=chatgpt.com))
* SME2 on mobile/on-device gives large multipliers compared to previous generation CPUs, but still not yet in the same class of throughput as server-grade GPUs, especially for larger LLMs.

***

### What the Expected Gaps Are / Where GPU Still Wins

Based on the data and what we know of hardware:

1. **Throughput (tokens/sec)**: GPUs still dominate especially as model size grows, when precision is FP16/BF16 or even FP8, and when batch size / context length is large.
2. **Latency to First Token**: GPUs tend to have much lower “warm up” and can start generation quickly. CPUs might have higher overheads, especially on the first token or for small batches / long contexts.
3. **Memory size & bandwidth**: GPU memory (HBM, large VRAM) gives a big advantage for large models; CPUs are often constrained by system memory bandwidth / cache latency if trying to load large model weights, attention state etc.
4. **Cost Efficiency at Lower Scales**: CPUs with AMX (or AVX) become more competitive when model sizes are modest, quantization is used, and throughput requirements are moderate. They may even beat GPUs in some “servers owned & operated” TCO when GPU hardware, power, cooling, etc. are factored in.
5. **Energy use / power draw**: For on-device or low batch settings, CPUs may be more efficient (per watt) vs powering big GPUs. But for sustained high throughput, GPUs may come out ahead in joules/token.

***

### Specific Approximate Comparisons / “Rule of Thumb” Based on Available Data

Here are some rough numbers / heuristics extrapolated from the sources above + known GPU performance:

| Scenario                                                                      | AMX/AVX CPU                                                                                                                                                                                                                                                                                                                                                                        | GPU (e.g. A100 / H100 / H200 / MI300X)                                                                                                |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Small model (\~3B param), quantized INT8, batch small**                     | \~50-100 t/s achievable on Xeon + AMX (with quantization) ([OpenMetal IaaS](https://openmetal.io/resources/blog/intel-amx-ai-inference-performance/?utm_source=chatgpt.com))                                                                                                                                                                                                       | Likely thousands of tokens/sec on a good GPU; easily 10×-30× faster in these scenarios                                                |
| **Medium model (\~20-70B), FP16/BF16 or quantized, long context, high batch** | CPU will often struggle: maybe tens of t/s, plus memory constraints, might push GPU bumps into hundreds to thousands of t/s, depending on stack and precision                                                                                                                                                                                                                      | GPUs shine here; especially H100 / MI300X / similar cards scale to higher contexts and larger batch sizes with much better throughput |
| **First token latency**                                                       | CPU + AMX might have first token in hundreds of ms (sometimes <200ms in good quantized paths) for small/medium models; RAG / large context raises that further. Presidio reports \~ <50ms in good setups for first token in “generic prompts” with AMX + quantization. ([Presidio](https://www.presidio.com/blogs/llms-on-intel-xeon-cpus-with-intel-amx/?utm_source=chatgpt.com)) | GPUs typically give tens of ms for first token in many production settings (with efficient I/O, optimized stack)                      |

***

### Gaps in Public Data (Open Points)

* I didn’t find many **direct head-to-head benchmarks** of *AMX CPU vs top GPUs* on large LLMs (70-400B), with the *same quantization*, same batch, same prompt size. Means we don’t have a fully apples-to-apples gap that is widely published.
* Similarly, SME / SME2 benchmarks in LLM inference (especially for large models) are less public; many SME2 results are mobile-/on-device oriented or microbenchmarked matrix multiplication, not full model decoding / generation.
* Also quantization formats, whether sparse operators are used, etc., make huge differences. Some CPU benchmarks use more aggressive quantization or pruning etc than GPU benchmarks, which can skew what “tokens/sec” means in terms of accuracy.

***

### Takeaways: How Much GPU Beats CPU (AMX/AVX/SME) + Where CPU Is Catching Up

Putting this all together:

* For **large models** (say >50-100B params) and where you need high throughput / many concurrent requests, GPUs remain the practical choice. The performance gaps are still large—often **5× to 30× or more** depending on configuration.
* For **medium or small models** (1-20B), especially quantized, CPU with AMX can close the gap significantly. Sometimes **within 2×-5× of GPU throughput** (depending on model, precision, batch size etc.), especially when you optimize carefully.
* On **latency / cost per model served** in low-throughput or intermittent settings, CPU + AMX / AVX / SME may be more cost-effective; you pay less for hardware, power, cooling, and maybe less engineering overhead around GPU fleet management.
* SME2 on mobile / device side is making strides, but not yet replacing server GPU performance for large LLMs.


# Cost Analysis

### 1. Dimensions of Cost

* **CapEx (hardware acquisition):**
  * GPUs (H100/MI300X): very high upfront, scarce supply, long lead times.
  * CPUs (Xeon/EPYC/Graviton): abundant, cheaper per socket, widely available across cloud and bare-metal.
* **OpEx (operational cost):**
  * **Power & cooling:** GPUs draw 350–700W per card; CPUs typically 100–300W per socket.
  * **Licensing & infra:** GPU clouds often include premium pricing; CPU instances are commodity-priced.
* **Developer/engineering cost:**
  * GPUs need specialized frameworks (CUDA, ROCm, Triton, paged attention).
  * CPUs leverage mainstream libraries (PyTorch + oneDNN, ONNX Runtime, OpenVINO).

***

### 2. Cost per Token (Illustrative)

| Workload                 | Hardware                 | Tokens/sec    | Instance Price (cloud est.) | $ per 1M Tokens | Notes                                      |
| ------------------------ | ------------------------ | ------------- | --------------------------- | --------------- | ------------------------------------------ |
| Small LLM (3B, INT8)     | Xeon AMX (m7i.xlarge)    | \~80–100      | \~$0.20/hr                  | \~$0.0007       | Cheap, CPU competitive                     |
| Small LLM (3B, INT8)     | A10 GPU (g5.xlarge)      | \~400–500     | \~$1.00/hr                  | \~$0.0005       | GPU slightly better but higher hourly rate |
| Mid LLM (13B, INT8)      | Xeon AMX (m7i.4xlarge)   | \~50          | \~$0.80/hr                  | \~$0.003–0.004  | CPUs slow down, cost rises                 |
| Mid LLM (13B, INT8/BF16) | A100 (p4d.24xlarge)      | \~1,500+      | \~$32/hr                    | \~$0.001–0.002  | GPUs more efficient at this scale          |
| Large LLM (70B, BF16)    | Xeon AMX (not practical) | <10           | \~$3/hr+                    | $0.03–0.05      | Not cost-effective                         |
| Large LLM (70B, BF16)    | H100 (p5.48xlarge)       | \~3,000–4,000 | \~$98/hr                    | \~$0.002–0.003  | Best option for massive models             |

*(Numbers are ballpark, based on AWS public pricing + reported throughput; adjust with your own benchmarks.)*

***

### 3. When CPUs Are More Cost-Effective

* **Quantized small/mid models (≤13B)**
* **Bursty/low-QPS traffic** (agents, RAG, edge workloads)
* **Tokenization, embedding, pre/post-processing** tasks
* **Commodity cloud or on-prem deployments** where GPUs are scarce/overpriced

***

### 4. When GPUs Win on Cost

* **Large models (≥30–70B)** where CPU throughput collapses
* **High-concurrency workloads** where GPU batching drives cost per token down
* **Training or fine-tuning** (CPUs not viable)

***

### 5. Strategic Takeaway

* **Cost efficiency is workload-dependent.**
  * CPUs with AMX/AVX/SME are cheapest for **smaller quantized models, agents, and spiky traffic.**
  * GPUs dominate cost-per-token for **large, steady, chat/research workloads.**
* The most economical architecture is **heterogeneous**:
  * **Route agents & utilities → CPUs**
  * **Route long-form inference → GPUs**


# Agent vs Chat/Deep-Research Inference

### Workload shapes (why they differ)

* **Agent inference** (tool-use, function calls, short bursts)
  * Spiky, I/O-bound, lots of small decode segments
  * Frequent context updates (tool outputs), smaller active batch
  * Latency tolerance varies by step; overall “time-to-task” matters more than raw tokens/sec
* **Chat / deep-research inference** (long context, long answers)
  * Sustained decoding, large prompts, bigger KV caches
  * Amenable to batching/throughput optimization
  * Sensitive to first-token latency and steady tokens/sec

### CPU vs GPU fit by workload

| Dimension                  | Agent (tools, routing, short bursts)                                                                                          | Chat / Deep-research (long ctx, long outputs)                                                                  |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Best silicon**           | **CPU-first** (AMX/AVX-512/SME) when models ≤13B and quantized (INT8/4-bit); GPUs for larger tools or vision/multimodal steps | **GPU-first**, esp. ≥13B, long contexts, or high concurrency; CPU viable for ≤7–13B quantized, low concurrency |
| **Batching gains**         | Low; steps are irregular → GPUs underutilize unless you coalesce across users                                                 | High; steady streams boost GPU utilization massively                                                           |
| **Perf/Watt**              | CPUs competitive for intermittent bursts (lower idle cost); SME2 compelling on-device                                         | GPUs win for sustained decoding and high batch                                                                 |
| **Latency to first token** | CPU can be good enough if model small + warm; otherwise GPU leads                                                             | GPU typically leads (kernel fusion, HBM)                                                                       |
| **Memory pressure**        | Lower (short prompts, short outputs per step)                                                                                 | High (long prompts, KV cache growth); favors GPUs with HBM or CPU with huge RAM but lower BW                   |
| **Ops complexity**         | Simple to scale horizontally with commodity CPUs                                                                              | GPU scheduling, batching, paged attention more involved but pays off at scale                                  |

### Practical routing rules (drop into Router/NodePool)

**By model size & precision**

* ≤7B, INT8/4-bit → **CPU preferred** (Xeon-AMX / EPYC-AVX512 / Arm-SME2 when available).
* 13B, INT8/4-bit → **CPU for agent; GPU for chat** (switch if prompt >16–32k or strict latency SLA).
* ≥33B or FP16/BF16 → **GPU** (both agent and chat), unless agent steps are rare and latency budget is loose.

**By prompt/context**

* Context ≤16k tokens → CPUs remain viable for agent; GPUs for long replies.
* Context >32k tokens or heavy RAG stitching → **GPU** (paged attention, KV offload efficiency).

**By concurrency**

* QPS < 2 per model instance (bursty agents) → **CPU** wins on TCO.
* QPS ≥ 5 with steady streams (chat, research) → **GPU** for utilization and joules/token.

**By SLA**

* p95 step latency ≤150 ms (agent tool loop) → small **CPU** models or **GPU** if model >13B / multimodal.
* First-token ≤75 ms and sustained ≥150 t/s/thread → **GPU**.

### Optimization knobs per target

**For CPU (agent-heavy)**

* Quantize to INT8 or 4-bit; enable AMX/VNNI/SME fast paths
* Use speculative decoding (draft-model 1–3B on CPU) then **verify on CPU/GPU** if needed
* KV-cache paging to system RAM; smaller heads / grouped-QK attention if available
* Fuse pre/post steps (tokenization, retrieval, tool adapters) on the same CPU host to avoid PCIe hops

**For GPU (chat/research)**

* Enable continuous batching & paged attention
* Use FP8/BF16 where quality allows; enable tensor-parallel for ≥70B
* Pin RAG pipelines close to GPU (GPU-resident embeddings, vector search cache, or at least NVMe cache)
* Warm pools to hit <50 ms first-token

### Suggested Cortensor policies (ready-to-implement)

1. **Policy: Workload-aware placement**

```
if job.type == "agent":
  if model.params <= 13B and quantized: target = CPU(AMX|AVX512|SME2)
  else: target = GPU
else if job.type in {"chat","deep_research"}:
  if model.params <= 7B and quantized and ctx_len <= 16k and qps < 2: target = CPU
  else: target = GPU
```

2. **Policy: ISA-aware CPU dispatch**

```
CPU_AMX  -> prefer INT8/BF16 kernels (oneDNN/OpenVINO)
CPU_AVX512-> prefer 4-bit/INT8 ggml/llama.cpp fast paths
CPU_SME2 -> ONNX Runtime + KleidiAI when available (Android/Arm nodes)
```

3. **Policy: Dynamic failover**

* If GPU queue depth > threshold or batcher starved, **reassign small agent steps to CPU** to preserve end-to-end task time.
* If CPU p95 > SLA for two windows, **promote** job class to GPU until backlog clears.

4. **Policy: Quantization tiers**

* **Agent tier**: 4-bit for tool calls & planners; 8-bit verifier/critic
* **Chat tier**: 8-bit or BF16 for final generation on GPU; keep reranker/embedding on CPU if helpful

### Example mappings

* **Agentic web-tool bot (7B, 8k ctx, bursts)** → CPU-AMX/AVX512, INT8, speculative decoding on 2–4 threads; promote rare long answers to GPU.
* **Analyst chat (13B, 32k ctx, steady traffic)** → GPU BF16/FP8 with continuous batching; CPU handles retrieval & post-proc.
* **On-device assistant (3–7B, mobile/edge)** → Arm-SME2 (as available) with 4-bit; offload long tasks to cloud GPU.

### How to measure (routing signals)

* **t/s**, **first-token ms**, **KV-cache MB/token**, **context len**, **QPS**, **burstiness factor** (p50 interarrival vs p95)
* Promote/demote rules on rolling windows (e.g., 60–120s) with hysteresis to avoid thrash

***

#### Bottom line

* **Agent workloads**: favor **CPUs** (AMX/AVX-512/SME2) for small/quantized models and spiky demand; they minimize idle cost and keep “time-to-task” low.
* **Chat/deep-research**: favor **GPUs** for long contexts and steady decoding; batching + HBM dominate cost/perf.
* A **heterogeneous policy** that auto-routes by **model size, precision, context, QPS, and SLA** will beat either CPU-only or GPU-only strategies on both cost and user experience.


# TCO Impact

### 1. Hardware Acquisition (CapEx)

* **GPUs:**
  * **High upfront cost**: NVIDIA H100 \~$25k–$35k per card; AMD MI300X similar.
  * **Supply-constrained**, long lead times, often bundled with premium OEM systems.
* **CPUs:**
  * Commodity pricing, already included in existing servers.
  * Adding AMX/AVX-512 support is *free* if you already run Sapphire Rapids / EPYC Zen 4.
  * Arm Graviton instances in cloud are cheaper per vCPU than GPU nodes.

👉 **Impact:** GPUs raise CapEx dramatically; CPUs leverage sunk infrastructure.

***

### 2. Operational Costs (OpEx)

* **Power & Cooling:**
  * GPUs draw **350–700W per card** (8x H100 system = 5–7 kW).
  * CPUs typically **150–300W per socket** (dual-socket Xeon ≈ 400–500W total).
  * In datacenter terms: **energy per token** is lower for GPU *at scale* (large batches), but higher for GPU *at low utilization*.
* **Cloud Pricing:**
  * GPU instances (e.g., AWS p5d.24xlarge) are **$90–$98/hour**.
  * CPU instances (m7i.4xlarge Xeon AMX) are **<$1/hour**.
  * For small/quantized models, CPU cost per million tokens can actually beat GPU.

👉 **Impact:** GPUs are more power-hungry and expensive hourly, but amortize better at high throughput. CPUs win when workloads are bursty or low-QPS.

***

### 3. Utilization Factor

* **GPUs must be fully loaded** (batching, continuous streams) to justify TCO. Idle GPU capacity is wasted CapEx + OpEx.
* **CPUs scale elastically** — already deployed for general compute, so inference can “borrow” unused cycles.

👉 **Impact:** TCO for GPUs is highly sensitive to utilization; CPUs are more forgiving.

***

### 4. Engineering / Software Overhead

* **GPUs:**
  * Require specialized kernels (CUDA, ROCm, Triton, paged attention).
  * Higher engineering investment in serving infra (batch schedulers, KV-cache offload).
* **CPUs:**
  * Leverage mainstream stacks (PyTorch + oneDNN, OpenVINO, ONNX Runtime).
  * Easier to integrate into existing server workflows.

👉 **Impact:** CPU inference reduces dev/ops overhead → lower “hidden TCO.”

***

### 5. Cost per Token (Illustrative)

| Workload | Hardware               | Tokens/sec  | $/hour (AWS est.) | $ per 1M tokens          |
| -------- | ---------------------- | ----------- | ----------------- | ------------------------ |
| 3B INT8  | Xeon AMX (m7i.xlarge)  | \~80–100    | $0.20             | \~$0.0007                |
| 3B INT8  | A10 GPU (g5.xlarge)    | \~400–500   | $1.00             | \~$0.0005                |
| 13B INT8 | Xeon AMX (m7i.4xlarge) | \~50        | $0.80             | \~$0.003–0.004           |
| 13B BF16 | A100 (p4d.24xlarge)    | \~1,500+    | $32               | \~$0.001–0.002           |
| 70B BF16 | Xeon AMX               | <10         | $3+               | $0.03–0.05 (impractical) |
| 70B BF16 | H100 (p5.48xlarge)     | 3,000–4,000 | $98               | \~$0.002–0.003           |

👉 **Impact:**

* For **small/quantized models**, CPUs are close or better in cost/token.
* For **large models**, GPUs dominate cost/token by an order of magnitude.

***

### 6. Strategic TCO Takeaway

* **GPU-only strategy**: High CapEx/OpEx, but best for large models and high concurrency. Risks: overprovisioning, idle burn.
* **CPU-only strategy**: Cheap and abundant, but throughput collapses beyond 13–20B models.
* **Hybrid strategy** (best TCO):
  * Route **agents, RAG, 3–13B quantized models** → CPUs (AMX/AVX-512/SME2).
  * Route **chat, deep research, ≥30B models** → GPUs.
  * This maximizes utilization of expensive GPUs, while lowering idle cost and power draw.

***

📌 **Bottom line:**

* GPUs maximize performance, but TCO is only optimal if you keep them fully utilized.
* CPUs reduce TCO for smaller models, bursty traffic, and quantized workloads.
* The most cost-effective infrastructure is **heterogeneous**, dynamically routing workloads by **model size, concurrency, and SLA**.


# Summary

The evolution of CPU instruction sets — **AVX, AMX, and SME** — is reshaping the role of CPUs in LLM inference. Once relegated to tokenization and orchestration, CPUs are now credible inference engines for **quantized small-to-medium models**, thanks to specialized matrix/vector operations tightly aligned with transformer workloads.

***

### Key Insights

#### **Performance Gains on CPUs Are Real**

* **Intel AMX** doubles or triples throughput on Xeon for INT8/BF16 models, reaching **50–120 tokens/sec** on 3–13B models.
* **AMD AVX-512** unlocks meaningful uplift in local inference, widely used in `llama.cpp`.
* **Arm SME2** delivers **3–5× AI uplifts** in mobile/on-device benchmarks, preparing Arm for cloud-scale deployments.

#### **GPUs Still Rule Large Models**

* For **20–70B+ models**, GPUs remain **5–30× faster** with lower latency.
* **HBM bandwidth** enables workloads CPUs cannot yet match.

#### **Agent vs Chat/Deep-Research Workloads**

* **Agent inference** (short bursts, tool calls) → CPU-friendly with ≤13B quantized models; CPUs minimize idle cost and shine in spiky, latency-tolerant scenarios.
* **Chat / deep-research inference** (long contexts, steady decode) → GPU-dominant; batching + HBM give GPUs cost/perf leadership.
* **Routing implication:** CPUs for agents and lightweight pipelines, GPUs for chat/research and sustained workloads.

#### **Cost Efficiency**

* **CPUs cheaper** for small/quantized models, bursty traffic, and edge deployments.
* **GPUs cheaper** per token for large models and high-concurrency workloads.
* Example: A 3B quantized model may be more cost-efficient on CPU AMX, while a 70B BF16 model is far more economical on GPU H100.

#### **Strategic Positioning**

* **CPUs excel** in quantized, cost-sensitive, or edge scenarios (RAG pipelines, lightweight agents).
* **GPUs excel** in maximum throughput, minimal latency, and large-model serving.
* **Heterogeneous orchestration** is optimal — route workloads dynamically by size, precision, and SLA.

#### **Industry Momentum**

* **Intel (AMX):** deeply integrated into PyTorch (oneDNN) and OpenVINO.
* **AMD (AVX-512):** framing EPYC as a GPU-light inference solution.
* **Arm (SME2):** extending LLM inference into mobile and preparing for Arm-cloud adoption.
* **Cloud Providers:** AWS, Azure, GCP exposing CPU ISAs in production instances.

***

### 📌 Final Conclusion

**AMX and SME2 are not GPU killers — they are GPU complements.**\
They broaden the deployment surface for LLM inference by making CPUs **practical, scalable, and cost-efficient** for a significant share of workloads.

* **Today:** Deploy **Xeon AMX / EPYC AVX-512** for 3–20B quantized models, agent pipelines, and RAG-style workloads.
* **Tomorrow:** **Arm SME2** will unlock on-device and Arm-cloud inference at scale.
* **Always:** **GPUs remain indispensable** for large models, long contexts, and high-throughput serving.

The future of AI infrastructure is **heterogeneous**: CPUs, GPUs, and emerging NPUs working together. Instruction set innovations ensure CPUs remain central — not as replacements for GPUs, but as **critical complements** in a layered AI execution fabric where **performance, cost, and workload shape deployment decisions.**


# Supported Models

Cortensor runs a curated catalog of **open-weight LLMs** across two primary engines:

* **Llamafile** – quantized GGUF models (CPU-friendly, can also use GPU where available)
* **Ollama** – full GPU models (for higher-end / dedicated GPU miners)

Internally, each model is packaged as a **Docker image** identified as:

* `cts-llm`, `cts-llm-1`, `cts-llm-2`, … `cts-llm-40`

These **`cts-llm-*` IDs are Docker image tags**, not the raw model names.\
Each image wraps one runtime engine (**llamafile** or **Ollama**) and one concrete model identifier (e.g. `deepseek-r1:8b-gpu`).

> ❗ This catalog will grow over time. New images will be added with higher IDs (`cts-llm-41`, `cts-llm-42`, …), so treat the tables below as **versioned snapshots** rather than a permanent, fixed list.

***

### Quantized Models (Llamafile)

**Engine:** `llamafile`\
**Indexes:** `0–11`\
**Hardware:** CPU-first, can use GPU where available\
**Purpose:** Maximum coverage across heterogeneous nodes (CPUs, smaller GPUs, edge machines) using **4–8 bit quantization**.

These images are ideal for:

* Nodes without a dedicated GPU
* Mixed-resource environments (small VPS, home PCs, edge hardware)
* High fan-out / broad geographic coverage

#### Model Families Covered

The current llamafile set includes quantized versions of:

* **Vision / Multimodal**
  * `llava-v1.5-7b-q4` (used as `default-gpu` on many nodes)
* **Reasoning & General LLMs**
  * **DeepSeek R1 Distill Llama 8B** (Q4)
  * **Meta Llama 3.1 8B Instruct** (Q4)
  * **Mistral 7B Instruct v0.3** (Q4)
  * **Granite 3.2 8B Instruct** (Q4)
  * **Qwen2.5 7B Instruct 1M** (Q4)
* **High-Capacity & Coder Variants**
  * **Qwen QwQ 32B** (Q4)
  * **Qwen3 4B** (Q8)
  * **Gemma 3 4B / 12B IT** (Q6 / Q4)
  * **DeepSeek R1 Distill Qwen 14B** (Q4)
  * **Qwen2.5 Coder 14B Instruct** (Q4)

These quantized models prioritize:

* Lower memory footprint
* Broad participation from smaller nodes
* “Good enough” quality for many general-purpose workloads and background jobs

***

### Full GPU Models (Ollama)

**Engine:** `ollama`\
**Indexes:** `12–40`\
**Hardware:** GPU nodes (NVIDIA strongly preferred)\
**Purpose:** High-quality, low-latency inference for more demanding workloads and higher-SLA routes.

These are **full GPU models** (not llamafile-style Q4/Q6 GGUFs). They are meant for:

* Dedicated or strong GPU miners
* Latency-sensitive user requests
* High-quality routing tiers

#### Model Families Covered

The current Ollama set spans several major model families:

* **Gemma 3**
  * 270M, 4B, 12B, 27B
* **DeepSeek R1**
  * 8B, 14B, 70B
* **GPT-OSS**
  * 20B, 120B
* **Granite**
  * Granite 4 3B
* **Ministral / Mistral**
  * Ministral 3 8B / 14B
  * Mistral 7B
* **Qwen 3 & Qwen 3 VL**
  * Qwen3 4B / 8B
  * Qwen3 VL 4B / 8B
* **Phi**
  * Phi-3 3.8B / 14B
  * Phi-4 14B
* **Llama 3.x**
  * Llama 3.2 1B / 3B
  * Llama 3.1 8B / 70B
* **Others**
  * Dolphin 3 8B
  * TinyLLaMA 1.1B
  * Falcon 3 3B / 7B / 10B

These are best suited to:

* Nodes with enough VRAM to serve these models efficiently
* High-SLA task classes
* Scenarios where quality/latency > footprint

***

### How the Mapping Works

At the **node / Docker level**, you mostly deal with:

* `cts-llm-*` → **Docker image ID**
* Each image contains:
  * The **engine** (`llamafile` or `ollama`)
  * The **model identifier** (e.g. `deepseek-r1:8b-gpu`, `Qwen2.5-7B-Instruct-1M-Q4_K_M`)

At the **network / session level**, Cortensor can:

* Route tasks by **model index** (0–40)
* Or use more descriptive labels via config/SDKs where needed

As we add more models, we’ll extend the table with new indices and images; this section stays as the canonical mapping.

***

### Appendix: Full Model Mapping

Below are the **current** model mappings used by Cortensor.

> 🧩 **Columns**
>
> * **Index** – numeric model index used in configs / selection
> * **Docker Image ID** – the `cts-llm-*` tag
> * **Engine** – `llamafile` or `ollama`
> * **Model Identifier** – actual model/runtime name inside the image
> * **Model Family / Size** – human-readable description
> * **Quantized?** – whether it’s a quantized GGUF (for llamafile) or full GPU model

***

#### Quantized Models – Llamafile (`0–11`)

| Index | Docker Image ID | Engine    | Model Identifier                                                       | Model Family / Size          | Quantized?  |
| ----: | --------------- | --------- | ---------------------------------------------------------------------- | ---------------------------- | ----------- |
|     0 | `cts-llm`       | llamafile | <p><code>default</code></p><p><code>default-gpu</code> (llamafile)</p> | LLaVA v1.5 7B Q4             | Yes – 4-bit |
|     1 | `cts-llm-1`     | llamafile | `DeepSeek-R1-Distill-Llama-8B-Q4_K_M`                                  | DeepSeek R1 Distill Llama 8B | Yes – 4-bit |
|     2 | `cts-llm-2`     | llamafile | `Meta-Llama-3.1-8B-Instruct.Q4_K_M`                                    | Llama 3.1 8B Instruct        | Yes – 4-bit |
|     3 | `cts-llm-3`     | llamafile | `Qwen_QwQ-32B-Q4_K_M`                                                  | Qwen QwQ 32B                 | Yes – 4-bit |
|     4 | `cts-llm-4`     | llamafile | `Mistral-7B-Instruct-v0.3.Q4_0`                                        | Mistral 7B Instruct v0.3     | Yes – 4-bit |
|     5 | `cts-llm-5`     | llamafile | `granite-3.2-8b-instruct-Q4_K_M`                                       | Granite 3.2 8B Instruct      | Yes – 4-bit |
|     6 | `cts-llm-6`     | llamafile | `Qwen2.5-7B-Instruct-1M-Q4_K_M`                                        | Qwen2.5 7B Instruct 1M       | Yes – 4-bit |
|     7 | `cts-llm-7`     | llamafile | `google_gemma-3-4b-it-Q6_K`                                            | Gemma 3 4B IT                | Yes – 6-bit |
|     8 | `cts-llm-8`     | llamafile | `Qwen_Qwen3-4B-Q8_0`                                                   | Qwen3 4B                     | Yes – 8-bit |
|     9 | `cts-llm-9`     | llamafile | `google_gemma-3-12b-it-Q4_K_M`                                         | Gemma 3 12B IT               | Yes – 4-bit |
|    10 | `cts-llm-10`    | llamafile | `DeepSeek-R1-Distill-Qwen-14B-Q4_K_M`                                  | DeepSeek R1 Distill Qwen 14B | Yes – 4-bit |
|    11 | `cts-llm-11`    | llamafile | `Qwen2.5-Coder-14B-Instruct-Q4_K_M`                                    | Qwen2.5 Coder 14B Instruct   | Yes – 4-bit |

***

#### Full GPU Models – Ollama (`12–40`)

| Index | Docker Image ID | Engine | Model Identifier      | Model Family / Size | Quantized?                     |
| ----: | --------------- | ------ | --------------------- | ------------------- | ------------------------------ |
|    12 | `cts-llm-12`    | ollama | `gemma3:270m-gpu`     | Gemma 3 270M        | No – full GPU                  |
|    13 | `cts-llm-13`    | ollama | `gpt-oss:20b-gpu`     | GPT-OSS 20B         | No – full GPU                  |
|    14 | `cts-llm-14`    | ollama | `deepseek-r1:8b-gpu`  | DeepSeek R1 8B      | No – full GPU                  |
|    15 | `cts-llm-15`    | ollama | `granite4:3b-gpu`     | Granite 4 3B        | No – full GPU                  |
|    16 | `cts-llm-16`    | ollama | `gpt-oss:120b-gpu`    | GPT-OSS 120B        | No – full GPU                  |
|    17 | `cts-llm-17`    | ollama | `deepseek-r1:70b-gpu` | DeepSeek R1 70B     | No – full GPU                  |
|    18 | `cts-llm-18`    | ollama | `gemma3:4b-gpu`       | Gemma 3 4B          | No – full GPU                  |
|    19 | `cts-llm-19`    | ollama | `gemma3:12b-gpu`      | Gemma 3 12B         | No – full GPU                  |
|    20 | `cts-llm-20`    | ollama | `ministral-3:8b-gpu`  | Ministral 3 8B      | No – full GPU                  |
|    21 | `cts-llm-21`    | ollama | `deepseek-r1:14b-gpu` | DeepSeek R1 14B     | No – full GPU                  |
|    22 | `cts-llm-22`    | ollama | `gemma3:27b-gpu`      | Gemma 3 27B         | No – full GPU                  |
|    23 | `cts-llm-23`    | ollama | `qwen3-vl:4b-gpu`     | Qwen3 VL 4B         | No – full GPU (vision-capable) |
|    24 | `cts-llm-24`    | ollama | `qwen3-vl:8b-gpu`     | Qwen3 VL 8B         | No – full GPU (vision-capable) |
|    25 | `cts-llm-25`    | ollama | `ministral-3:14b-gpu` | Ministral 3 14B     | No – full GPU                  |
|    26 | `cts-llm-26`    | ollama | `qwen3:4b-gpu`        | Qwen3 4B            | No – full GPU                  |
|    27 | `cts-llm-27`    | ollama | `qwen3:8b-gpu`        | Qwen3 8B            | No – full GPU                  |
|    28 | `cts-llm-28`    | ollama | `mistral:7b-gpu`      | Mistral 7B          | No – full GPU                  |
|    29 | `cts-llm-29`    | ollama | `phi3:3.8b-gpu`       | Phi-3 3.8B          | No – full GPU                  |
|    30 | `cts-llm-30`    | ollama | `phi3:14b-gpu`        | Phi-3 14B           | No – full GPU                  |
|    31 | `cts-llm-31`    | ollama | `llama3:1b-gpu`       | Llama 3.2 1B        | No – full GPU                  |
|    32 | `cts-llm-32`    | ollama | `llama3:3b-gpu`       | Llama 3.2 3B        | No – full GPU                  |
|    33 | `cts-llm-33`    | ollama | `llama3:8b-gpu`       | Llama 3.1 8B        | No – full GPU                  |
|    34 | `cts-llm-34`    | ollama | `llama3:70b-gpu`      | Llama 3.1 70B       | No – full GPU                  |
|    35 | `cts-llm-35`    | ollama | `phi4:14b-gpu`        | Phi-4 14B           | No – full GPU                  |
|    36 | `cts-llm-36`    | ollama | `dolphin3:8b-gpu`     | Dolphin 3 8B        | No – full GPU                  |
|    37 | `cts-llm-37`    | ollama | `tinyllama1.1b-gpu`   | TinyLLaMA 1.1B      | No – full GPU                  |
|    38 | `cts-llm-38`    | ollama | `falcon3:3b-gpu`      | Falcon 3 3B         | No – full GPU                  |
|    39 | `cts-llm-39`    | ollama | `falcon3:7b-gpu`      | Falcon 3 7B         | No – full GPU                  |
|    40 | `cts-llm-40`    | ollama | `falcon3:10b-gpu`     | Falcon 3 10B        | No – full GPU                  |


# Type of Services

Cortensor offers a variety of AI services tailored to meet diverse application needs, evolving from basic inference tasks to more specialized capabilities. Not all services require real-time responses, allowing for flexible and efficient use of network resources.

**Overview**

Cortensor’s services cater to different intelligence needs, ensuring that applications can leverage AI capabilities effectively, whether they require immediate responses or can operate with delayed processing.

## **Key Services**

### **Inference Services**:

* Provides AI inference capabilities for applications to submit prompts and receive completions.
* Supports both real-time and non-real-time processing, enabling flexible integration.
* Utilizes Llama 3 models, both quantized and regular, to accommodate various hardware capabilities.
* Includes tasks such as classification, prediction, and content generation.

### **Prediction Services**:

* Analyzes historical data to predict future trends and outcomes.
* Essential for applications in finance, marketing, and supply chain management.
* Utilizes advanced machine learning algorithms for accurate forecasts.

### **Generation Services**:

* **Synthetic Data Generation**: Creates artificial data for training AI models, enhancing performance and addressing data scarcity.
* **Content Generation**: Produces text, images, and other content types based on user prompts.
* **Data Augmentation**: Improves the robustness and performance of AI models through data augmentation techniques.

### **Classification Services**:

* Categorizes data into predefined classes for applications like spam detection, image classification, and document categorization.
* Identifies and classifies entities within text, useful for NLP applications.
* Classifies text based on sentiment, aiding in customer feedback analysis and social media monitoring.

### **Oracle Services**:

* Offers decentralized oracle services that provide reliable data feeds to smart contracts.
* Ensures applications receive accurate and verified external data, crucial for blockchain-based operations.

### **AI Marketplace**:

* Facilitates a marketplace where developers can share, sell, and purchase AI models and services.
* Supports the sharing of fine-tuned models with watermarks to incentivize contributions.
* Allows for the creation and distribution of prompts to be used with inference sessions.
* Future plans include integrating AI agents that can interact with the network and be hosted on-chain, enhancing the functionality and reach of AI services.


# Consensus & Validation

Consensus and validation are essential components of Cortensor's decentralized AI network, ensuring the accuracy, reliability, and integrity of AI inference tasks. This section outlines the mechanisms and processes that enable effective consensus and validation within the Cortensor ecosystem.

## **Overview**

Cortensor employs robust consensus mechanisms and comprehensive validation processes to maintain trust and reliability in the network. These mechanisms ensure that AI inference results are accurate, tasks are completed efficiently, and malicious activities are minimized.

## **Key Mechanisms**

### **Proof of Inference (PoI) / Proof of Useful Work (PoUW)**:

* A consensus mechanism that validates the completion and accuracy of AI inference tasks.
* Ensures that the work performed by miner nodes is useful and meets the required standards.

### **Validation Nodes**:

* Specific nodes responsible for verifying the accuracy of inference results.
* Conduct semantic checks, embedding comparisons, and checksum verifications to ensure result integrity.

### **Reputation and Scoring**:

* Nodes build a reputation based on their performance in task execution and validation.
* Higher reputation scores increase the likelihood of receiving more tasks and rewards.

### **Encrypted Communication**:

* All data transmission within the network is encrypted to ensure privacy and integrity.
* Ensures secure communication between nodes during the validation process.

## **Validation Process**

1. **Result Submission**:
   * Miner nodes submit inference results through encrypted channels.
   * Results are initially aggregated and verified by router nodes.
2. **Validation Checks**:
   * Validation nodes perform a series of checks to verify the accuracy of the results.
   * Methods include semantic checks to ensure logical consistency, embedding comparisons to check for similarity, and checksum verifications to confirm data integrity.
3. **Consensus Formation**:
   * Multiple validation nodes must agree on the accuracy of the results for consensus to be reached.
   * This decentralized approach ensures that no single node can manipulate the outcome.
4. **Reputation Updates**:
   * Nodes' reputations are updated based on their performance in the validation process.
   * Accurate and timely validations improve a node’s reputation, while incorrect validations can reduce it.

## **Security Measures**

### **Staking and Incentives**:

* Nodes stake tokens to participate in the network, ensuring their commitment and reducing the risk of malicious behavior.
* Incentives are distributed based on performance, encouraging high-quality contributions.

### **Fault Tolerance**:

* Implements fault-tolerant mechanisms to handle node failures and ensure continuous network operation.
* Ensures that consensus and validation processes are not disrupted by individual node issues.


# Building Trustless AI

Proof of Inference (PoI) & Proof of Useful Work (PoUW)

From the beginning, Cortensor was founded on a simple but critical belief: **AI inference must be verifiable, not just fast**. Speed without trust leads to opaque systems, while verifiable inference ensures accountability, reliability, and fairness across the decentralized network.

To achieve this, Cortensor introduces two complementary validation layers:

* **Proof of Inference (PoI)** – validating **consistency** of outputs.
* **Proof of Useful Work (PoUW)** – validating **quality and usefulness** of outputs.

Together, they form the foundation of **trustless AI** within the Cortensor network.

***

### Proof of Inference (PoI)

* **Status**: Live today as dashboard tooling.
* **Mechanism**: Measures **output consistency** across nodes via embedding similarity.
* **Goal**: Ensure different nodes return aligned results for the same task.
* **Impact**: Forms the baseline for **trust and SLA enforcement** in decentralized inference.

PoI is the first safeguard that prevents invalid or divergent outputs from propagating across the network.

***

### Proof of Useful Work (PoUW)

* **Status**: In design, not yet fully integrated.
* **Mechanism**: Validator nodes perform **prompt-based scoring** to assess outputs.
* **Focus**: Evaluates **usefulness, relevance, and correctness** of responses.
* **Goal**: Build a **decentralized reputation layer**, rewarding nodes for useful, high-integrity outputs.

PoUW extends beyond raw consistency (PoI) by embedding **qualitative evaluation** directly into the validation process.

***

### Alignment with Industry Research

Recent research and releases, particularly from **OpenAI**, validate Cortensor’s architectural direction:

* **Prover–Verifier Games** – OpenAI’s “universal verifier” introduces a loop where a smaller model evaluates and scores the reasoning of a larger model.
* **Verifier Role** – Lightweight verifier models are **scalable for production**, directly scoring reasoning chains.
* **Convergence** – OpenAI’s move toward prover–verifier architectures confirms the need for **structured validation loops**, a principle Cortensor has embedded since inception.

Cortensor anticipated this trajectory:

* One model generates, another validates.
* Validators use **prompt-based metrics** to score quality.
* **Reputation and incentives** are tied to high-value, verifiable output.

***

### Industry Example: OpenAI Prover–Verifier Loop

* **Mechanism**:
  * “Helpful” persona: generates solutions.
  * “Sneaky” persona: attempts to mislead.
  * Verifier network: flags errors and sharpens validation.
* **Integration**: Used in GPT-4 fine-tuning pipelines and expected in GPT-5 mainline deployments.
* **Significance**: Demonstrates a **production-ready model-based critic system**, replacing portions of human feedback in RLHF training.

This confirms the **inevitability of verifier-driven validation** at scale – a core design principle already embedded in Cortensor’s roadmap.

***

### Why This Matters

* **Trust**: Inference without validation is opaque and unverifiable.
* **Accountability**: PoI ensures consistency; PoUW ensures usefulness.
* **Decentralization**: Validators distribute responsibility, ensuring no single authority defines “truth.”
* **Sustainability**: Tying validation to incentives creates a **self-reinforcing system** of reliable AI outputs.

Cortensor was built for a future where inference is not only fast, but **verifiable, open, and decentralized**. The ecosystem is now converging on the direction we committed to from the start.

***

### References

* [Proof of Inference (PoI) & Proof of Useful Work (PoUW)](https://docs.cortensor.network/technical-architecture/consensus-and-validation/proof-of-inference-poi-and-proof-of-useful-work-pouw)
* [Proof of Useful Work (PoUW)](https://docs.cortensor.network/technical-architecture/consensus-and-validation/proof-of-useful-work-pouw)
* Rohan Paul on OpenAI’s verifier loop [Tweet](https://x.com/rohanpaul_ai/status/1951400750187209181)


# Proof of Inference (PoI) & Proof of Useful Work (PoUW

## **Proof of Inference (PoI)**:

* **Purpose**: To ensure that AI inference tasks are performed correctly and consistently across different nodes using the same model.
* **Mechanism**:
  * Nodes perform AI inference tasks and generate outputs.
  * Outputs are compared using embeddings and vector distances to measure similarity.
  * High similarity between outputs from different nodes indicates that the nodes have performed the task correctly, providing consensus on the inference results.
  * This process ensures that nodes are generating accurate and reliable outputs based on the same AI model.

## **Proof of Useful Work (PoUW)**:

* **Purpose**: To validate the correctness and usefulness of AI inference results, ensuring they are meaningful and can contribute to further knowledge.
* **Mechanism**:
  * Nodes generate AI inference results, which are then reviewed by other nodes or validators.
  * Validators assess the usefulness of the results by checking if the information generated is correct, relevant, and can be extended as knowledge.
  * This might involve additional checks, such as semantic consistency, logical coherence, or practical applicability of the generated information.
  * Validators provide feedback or scores on the results, helping to determine their usefulness.
  * This process ensures that AI inference outputs are not only accurate but also valuable and applicable in real-world scenarios.

## Summary

### **Proof of Inference (PoI)**:

* Focuses on ensuring consistency and correctness of inference tasks.
* Uses embeddings and vector distances to measure similarity between outputs.

### **Proof of Useful Work (PoUW)**:

* Focuses on validating the correctness and practical usefulness of inference results.
* Involves peer review or validation to assess the relevance and applicability of the generated information.

Both mechanisms work together to maintain the integrity and reliability of AI inference tasks within the Cortensor network, ensuring that outputs are both accurate and valuable.


# aka Mining

Cortensor's mining process is a cornerstone of its decentralized AI network, designed to ensure the quality, reliability, and efficiency of AI inference services. Unlike traditional mining, which focuses primarily on validating transactions or generating new blocks, Cortensor's approach integrates advanced mechanisms such as Proof of Inference (PoI) and Proof of Useful Work (PoUW). These mechanisms are crucial for verifying that the computational work performed by nodes is both accurate and valuable.

#### Proof of Inference (PoI)

The Proof of Inference mechanism ensures that AI inference tasks are performed correctly and consistently across different nodes using the same model. In this process, nodes generate outputs from AI inference tasks, which are then compared using embeddings and vector distances to measure similarity. High similarity between outputs from different nodes confirms that the tasks have been executed accurately, providing consensus on the inference results. This method guarantees that the outputs are reliable and consistent across the network, reinforcing the network's overall integrity.

#### Proof of Useful Work (PoUW)

Proof of Useful Work goes a step further by validating not just the accuracy but also the practical usefulness of the AI inference results. In this process, nodes generate inference results that are subsequently reviewed by other nodes or validators. These validators assess whether the information produced is correct, relevant, and can be extended as knowledge. Additional checks might include evaluating the semantic consistency, logical coherence, and practical applicability of the generated data. This rigorous validation process ensures that the AI outputs are not only accurate but also valuable and applicable in real-world scenarios.

#### Gamified Quality Control

Cortensor employs a unique gamified approach to maintain high standards of quality control. Miners are periodically engaged in "games" that test their ability to perform various AI tasks. This process categorizes and ranks miners based on their performance, ensuring that only the most reliable nodes are prioritized for user requests. By incentivizing miners to continuously improve their capabilities, the network maintains a high level of service quality.

#### Mining Incentives

Cortensor's mining incentives are designed to reward miners for their contributions to the network. Miners earn base rewards for participating in network maintenance and AI inference tasks, distributed in $COR tokens. Performance-based rewards provide additional incentives for miners who excel in the gamified quality control processes or who complete particularly complex or valuable tasks. Miners can also stake $COR tokens to participate in higher-value tasks, further committing to the network's success.

#### Dynamic Role Allocation

In Cortensor's network, mining roles are dynamically allocated based on a miner's capabilities and performance. High-performing miners may be assigned more complex tasks or take on additional responsibilities, such as validating other miners' work. This flexibility ensures that the network operates at peak efficiency, with tasks matched to the most suitable nodes.

#### Unique Contributions to the AI Ecosystem

Cortensor’s mining process is not just about validating transactions or generating tokens—it’s about building a robust, reliable, and dynamic AI network that adapts to the needs of its users. Miners play a crucial role in supporting the AI ecosystem by generating valuable data, validating AI models, and maintaining the overall health and security of the network. This comprehensive approach sets Cortensor apart as a next-generation decentralized AI platform that prioritizes both performance and innovation, ensuring that AI inference outputs are accurate, useful, and valuable.


# Proof of Useful Work (PoUW)

Proof of Useful Work (PoUW) serves as a cornerstone validation mechanism in the Cortensor network. While Proof of Inference (PoI) focuses on embedding vector distances to ensure consistency and reliability of AI outputs, PoUW evaluates the quality, relevance, and correctness of results through pre-defined prompts and templates. Together, these complementary systems ensure a robust decentralized framework for validating tasks and outputs.

***

## **How PoUW Works**

1. **Task Submission**\
   Users submit tasks to the network, and miners generate AI inference outputs based on the requirements. These outputs are evaluated using model-specific prompts to verify their quality and adherence to the task specifications.
2. **Validation by Validators**
   * **Prompt-Based Assessment**: Validators use pre-defined prompts and templates tailored to specific tasks or models. These prompts are designed to assess key metrics such as relevance, accuracy, and usefulness.
   * **Scoring**: Validators assign scores to outputs, typically on a numerical scale (e.g., 1-10), based on task-specific criteria provided in the prompts.
   * **Collaborative Validation**: Validators pool their scores, cross-referencing results to achieve a consensus on the quality and validity of outputs. This collaborative approach mitigates individual bias and ensures fairness.
3. **Integration with NodeReputation**\
   Validator scores are fed into the NodeReputation system, influencing miner rankings and incentivizing consistent performance. Reliable miners are rewarded, while those producing subpar outputs see a decline in their reputation scores.

***

## **How PoUW Differs from PoI**

* **PoUW**: Focuses on output validation through task-specific prompts and templates, ensuring the relevance and quality of the task completion. Validators actively use models to perform evaluations.
* **PoI**: Primarily measures embedding vector distances between outputs from different nodes. This process ensures consistency and reliability when the same input is processed across multiple nodes, identifying variations and confirming results.

Together, PoUW and PoI form a robust dual-layer validation mechanism:

* PoI ensures **output consistency** across decentralized nodes.
* PoUW ensures **output relevance and quality** using task-specific evaluations.

***

## **Efficient Sampling for Validation**

To maintain scalability, the Cortensor network employs task sampling:

* Only a subset of tasks is selected for validation.
* Validators focus on these tasks to balance efficiency with thoroughness.
* Sampling ensures the network can scale while maintaining high validation accuracy.

For more details, refer to the [Sampling in Large Distributed Systems Documentation](https://docs.cortensor.network/technical-architecture/consensus-and-validation/sampling-in-large-distributed-systems).

***

## **Relation to Other Modules**

* **NodeStats**: Captures validation performance, integrating it into long-term metrics for miner and validator behavior.
* **Cognitive Module**: Oversees mining processes and validation orchestration, ensuring the system aligns with PoUW and PoI standards.
* **Session Module**: Manages user task submissions and validation outcomes, providing seamless integration for miners, validators, and users.

***

## **Key Benefits of PoUW**

* **Task-Specific Validation**: Pre-defined prompts ensure outputs align with task requirements.
* **Decentralized Trust**: Validators operate independently to provide unbiased evaluations.
* **Scalability**: Sampling ensures efficient validation without compromising quality.
* **Fair Rewards**: Integration with NodeReputation incentivizes meaningful contributions and reliable outputs.

***

## **Future Enhancements**

* **Dynamic Prompt Systems**: Expanding templates for more complex and diverse AI tasks.
* **Enhanced Validator Incentives**: Rewarding accuracy and consistency in validation efforts.
* **Real-Time Feedback**: Providing immediate insights into validation processes for users and miners.


# Proof of Useful Work (PoUW) State Machine

The Proof of Useful Work (PoUW) state machine is a critical component of the Cortensor network, ensuring that AI inferencing tasks are executed collaboratively and efficiently across a decentralized network of miners. This cognitive component orchestrates the flow of tasks, manages the correctness of outputs, and maintains the integrity of the network through a series of states. Each state in the PoUW state machine is governed by smart contracts, which facilitate interactions among miners and ensure that tasks are completed accurately and on time.

<figure><img src="/files/fBXWCUavqXr5WWQPoIUp" alt=""><figcaption></figcaption></figure>

## **Overview**

The PoUW state machine in Cortensor operates as a sophisticated state-based mechanism that manages the distribution and processing of AI inferencing tasks across the network. This mechanism is designed to handle the complexities of decentralized AI workloads, where multiple miners collaborate to solve problems by contributing to different stages of the task. The state machine controls the flow of work from the initiation of a session to the final submission of results, ensuring that the network functions without centralized oversight while maintaining high standards of accuracy and reliability.

## **Key Components of the PoUW State Machine**

1. **Smart Contract Facilitation**
   * Smart contracts are central to the operation of the PoUW state machine, as they carry the state of each session (or virtual block) and govern the selection and coordination of miners. These contracts are responsible for enforcing the rules of the state machine, ensuring that miners adhere to the prescribed workflow and that tasks are completed in a decentralized manner.
2. **Session Creation and Management**
   * A session in Cortensor is akin to a virtual block, where a set of randomly selected miners work together to solve an AI-related task. The session begins in the "request" state, where the network randomly selects miners to initiate the session. Once the miners are selected, they are notified via events triggered by the smart contract to begin work.
3. **State Transitions and Task Execution**
   * **Request State:** The session starts in the request state, where miners are randomly selected to create the session. This state marks the beginning of the task and involves the allocation of miners based on their capabilities.
   * **Create State:** In this state, the selected miners generate the initial structure of the session, such as defining fields, topics, or domains based on predefined prompts. This is a crucial phase where the foundational elements of the task are established. If a miner fails to produce the required output or does not respond within the allocated time, the network automatically reassigns the task to another miner to prevent a single point of failure.
   * **Prepare State:** After the initial structure is created, the session moves to the prepare state, where miners extend the work done in the create state. They generate additional related information, such as questions or subdomains, that will be used in subsequent states. The output from this state is then used to select another set of miners for further processing.
   * **Active State:** In this state, multiple miners work concurrently to generate outputs based on the inputs provided in the previous states. This collaborative effort ensures that the task is approached from multiple perspectives, increasing the likelihood of generating high-quality results.
   * **Precommit State:** Miners submit the hash of their output during this stage, without revealing the actual data. This "precommit" step is crucial for maintaining the integrity of the process, as it prevents bad actors from altering their outputs based on the work of others. The precommit state adds a layer of security by ensuring that the outputs are consistent and verifiable in the next stage.
   * **Commit State:** In the commit state, miners submit their actual inference outputs, which are then compared against the hashes submitted in the precommit state. This comparison ensures that the outputs are genuine and have not been tampered with. The consistency between the precommit hash and the actual output is critical for validating the results.
   * **End State:** The session concludes in the end state, where the outputs are finalized and the session (or virtual block) is completed. The results are then cleaned up, and the session is recorded as a finished block. This state also marks the point where the game-like process can begin anew, with a new set of tasks and miners.
4. **Validation and Quality Control**
   * **Proof of Inference (PoI):** During the validation phase, the network measures the embedding vector distance between outputs to ensure that miners used similar or identical models to generate the data. This step verifies that the outputs are consistent and adhere to the expected standards.
   * **Proof of Useful Work (PoUW):** PoUW further validates the correctness, usefulness, and semantic information of the outputs by utilizing additional LLM models. This process ensures that the work produced during the session is not only accurate but also valuable and relevant to the task at hand.

## **Ensuring Decentralized Quality Control**

Cortensor’s PoUW state machine is designed to maintain a high standard of service quality across a decentralized network. By using a state machine that controls the flow of tasks and validates outputs through PoI and PoUW, Cortensor can effectively measure the capabilities and reliability of individual nodes. The system’s flexibility allows for the introduction of additional states or levels to further classify nodes based on their performance, ensuring that only the most capable nodes serve user requests.

## **Extending the State Machine for Scalability and Future Services**

The PoUW state machine is inherently extendable, allowing Cortensor to introduce new levels of complexity and classification as the network grows. This adaptability ensures that the system can scale with increasing demand and can classify nodes according to their suitability for different types of tasks. One of the significant future applications of this state machine is in synthetic data generation. As AI models continue to evolve, the demand for high-quality synthetic data will grow, and the PoUW state machine can be extended to manage and validate these tasks within the network. This capability is one of the reasons it is called "Proof of Useful Work"—because it not only verifies the correctness of AI inferences but also facilitates the creation of valuable outputs that can be used for various AI-driven services, including synthetic data generation.

## **Conclusion**

The PoUW state machine is the core of Cortensor’s decentralized AI inference network, controlling the flow of tasks, ensuring the correctness of outputs, and maintaining the integrity of the network. By leveraging smart contracts and a sophisticated state-based workflow, Cortensor can deliver high-quality AI services in a decentralized manner. The state machine not only supports the collaborative efforts of miners but also provides a robust mechanism for validating and verifying the work produced, ensuring that the network remains reliable, scalable, and secure. This decentralized approach to quality control is essential for Cortensor's mission to democratize AI and make advanced AI models accessible to a broader audience. Moreover, its extensibility allows it to support future services like synthetic data generation, further enhancing the network's value and utility.


# Miner & Oracle Nodes in PoUW State Machine

In the Cortensor network, **Miner Nodes** and **Oracle Nodes** work together to run the **Proof of Useful Work (PoUW)** state machine. This system ensures efficient, fair, and reliable execution of AI inference tasks in a decentralized manner. The Miner Nodes perform the AI work across various states, while Oracle Nodes monitor the system's flow to ensure that all tasks are completed on time and that the network progresses smoothly.

### **Miner Node Workflow**

Miner Nodes are responsible for executing tasks across a series of state transitions in the PoUW state machine. These states include:

1. **Request**: The network randomly selects a Miner Node to start a session. The selected Miner Node is required to complete and submit AI inference work within a specified period (e.g., 5 seconds). Failure to do so triggers Oracle Nodes to request the network to reassign the task to another Miner.
2. **Create**: The selected Miner generates an initial output, such as a set of fields or topics, based on predefined prompts. If the Miner fails to submit the necessary data within the set timeframe, Oracle Nodes request the network to select another Miner.
3. **Prepare**: In this state, the output generated in the Create state is expanded upon. The selected Miner uses the initial output to generate further questions or relevant data for the next step. The complexity of the task is higher in this state, and Miners are again monitored by Oracle Nodes to ensure deadlines are met.
4. **Precommit**: A set of Miners is selected to perform useful work (e.g., generating answers based on the previous states' output). Miners submit a hash of their work during this stage to prevent dishonest behavior and tampering.
5. **Commit**: The Miners reveal their actual work, and it is verified against the hash submitted during the Precommit stage. Once verified, the session progresses to the final state.
6. **End**: The session concludes, and the results are finalized. Oracle Nodes request the network to clean up the session and prepare for the next.

Miner Nodes must complete their tasks within the assigned timeframes. Failure to do so can negatively impact their **reputation**, which affects future **network incentives** and their ability to receive more tasks.

### **Role of Oracle Nodes**

Oracle Nodes do not assign tasks but play a critical role in ensuring that the PoUW state machine operates smoothly and within the required time constraints. They monitor the state transitions and act as the sole mechanism that requests the network or smart contracts to:

* Transition from one state to another.
* Reassign tasks to new Miner Nodes when the current Miners fail to meet the deadlines.

For example, if a Miner Node does not complete the Create state work within the specified period, the Oracle Node will request the network to move the task to another Miner. Oracle Nodes ensure that tasks are completed in a timely fashion and maintain fairness across the network by holding all Miner Nodes to the same standards.

### **Future Automation with Chainlink Keepers**

Currently, Cortensor operates the Oracle Nodes manually to monitor and regulate the state transitions. However, as the network matures, the plan is to transition to using **Chainlink’s Automation tool, Keepers Registry**. This decentralized network of off-chain nodes will handle registered jobs (upkeeps) in a trust-minimized manner, triggering state transitions based on pre-configured conditions, such as time-based or event-driven actions.

This automation will ensure a fully decentralized, reliable, and scalable mechanism for state transitions, minimizing the need for manual interventions and improving network efficiency. This transition is scheduled for implementation closer to the **testnet** phase.

### **Why PoUW and Oracle Nodes Matter**

The PoUW state machine, monitored by Oracle Nodes, ensures that the Cortensor network can handle AI inference tasks efficiently and securely. By coordinating Miner Nodes and ensuring timely execution of tasks, Oracle Nodes contribute to the overall quality, fairness, and scalability of the network. This system can also be extended in the future to generate and provide services like **synthetic data generation**, showcasing the broader potential of the **Proof of Useful Work** mechanism.

### **Conclusion**

The combined efforts of Miner and Oracle Nodes ensure the integrity and efficiency of Cortensor’s decentralized AI inference network. As the network evolves, Oracle Nodes will play a critical role in ensuring smooth operation and maintaining fairness among Miner Nodes. Their regulation of the PoUW state machine will evolve through automation, further solidifying Cortensor’s commitment to a decentralized, scalable, and high-quality AI service network.


# Sampling in Large Distributed Systems

As we scale Cortensor’s decentralized AI inference network, ensuring the health and quality of the system becomes paramount. A critical aspect of this is the sampling process for Proof of Work (PoW), Proof of Inference (PoI), and Proof of Useful Work (PoUW). To maintain scalability and quality of supply across a large distributed network, it’s essential to determine an effective sample rate. Here’s how we are thinking about this process:

### Factors to Consider

* **Total Number of Nodes**: The total number of active nodes (miners) in the system.
* **Desired Confidence Level**: The statistical confidence level needed to ensure network health and reliability.
* **Node Variability**: The expected variability in node behavior and performance, which can impact the network's overall health.
* **Operational Constraints**: Network and computational limitations for sampling, processing, and reporting results.

### Example Calculation

Let’s assume the following for our sampling approach:

* **Total number of nodes**: 1,000,000
* **Desired confidence level**: 95%
* **Confidence interval (margin of error)**: ±1%
* **Expected variability**: 50% (most conservative estimate)

Using these assumptions, we apply the sample size formula for a proportion:

$$
n = \frac{Z^2 \cdot p \cdot (1 - p)}{e^2}
$$

Where:

* ( n ) = required sample size
* ( Z ) = Z-value (1.96 for 95% confidence level)
* ( p ) = estimated proportion (0.5 for maximum variability)
* ( e ) = margin of error (0.01 for ±1%)

Substituting the values:

$$
n = \frac{1.96^2 \cdot 0.5 \cdot (1 - 0.5)}{0.01^2}
$$

$$
n = \frac{3.8416 \cdot 0.25}{0.0001} = \frac{0.9604}{0.0001} = 9604
$$

So, approximately 9,604 nodes need to be sampled daily to achieve a 95% confidence level with a ±1% margin of error.

### Practical Considerations

* **Sampling Rate**: Given the need to sample 9,604 nodes per day from a pool of 1,000,000, the daily sampling rate would be approximately 0.96% of the total nodes.
* **Sampling Interval**: To evenly distribute the sampling load over 24 hours, we would sample approximately 400 nodes per hour (9,604 nodes / 24 hours).
* **Batch Processing**: For operational efficiency, hourly sampling can be broken down into smaller batches (e.g., 100 nodes every 15 minutes), distributing the computational load.

### Implementation Strategy

* **Dynamic Sampling**: Implement a dynamic sampling approach where the sample size adjusts based on real-time data and system conditions. This allows for more flexible and responsive monitoring of network health.
* **Round-Robin Selection**: Use a round-robin selection mechanism to ensure that all nodes are sampled over time, promoting fairness and comprehensive coverage.
* **Health Metrics**: Establish clear health metrics and thresholds for nodes based on the sampled data to ensure that only healthy and reliable nodes continue participating in the network.
* **Automated Alerts**: Set up automated alerts for nodes that fall below the health thresholds, triggering immediate remedial actions to maintain network integrity.

### Conclusion

This structured approach to sampling in Cortensor’s PoW - PoI, and PoUW processes is designed to balance scalability with the quality of supply in a large distributed system. By carefully selecting a sample size and implementing dynamic, real-time adjustments, we can ensure that the network remains healthy and reliable as it scales. The ongoing monitoring and adaptive strategies will play a crucial role in maintaining the high standards of performance and security expected in Cortensor’s decentralized AI network.


# Parallel Processing

Parallel processing in Cortensor is designed to enhance reliability and provide users with multiple validated outputs for the same input, offering greater flexibility and trust in a decentralized environment. Unlike traditional AI systems, where tasks are processed sequentially or in isolated environments, Cortensor leverages multiple miners to process the same input simultaneously, ensuring consistent and reliable results in untrusted environments.

### Key Steps in Parallel Processing

1. **Same Input, Multiple Outputs**\
   In Cortensor, the same input is distributed to multiple miners, each independently processing the task. This approach ensures redundancy and provides diverse outputs, allowing users to choose the result that best meets their needs.
2. **PoI Validation for Trust**\
   Cortensor’s Proof of Inference (PoI) system validates each output against predefined criteria, ensuring the quality and reliability of results. This process is crucial in untrusted environments, where the integrity of results might otherwise be compromised. PoI ensures that only valid and meaningful outputs are presented to the user.
3. **User-Selectable Outputs**\
   By generating multiple validated outputs for the same input, Cortensor offers users the flexibility to select the most suitable option. This feature is particularly beneficial for applications requiring high accuracy, diverse perspectives, or customizable results.
4. **Enhanced Reliability**\
   The decentralized execution of tasks across multiple miners not only improves fault tolerance but also increases the reliability of the network. Redundant processing ensures that even if some miners produce incorrect outputs, the PoI system identifies and excludes them, maintaining the overall integrity of the results.

### Benefits of Cortensor's Parallel Processing

* **Reliability in Untrusted Environments**: By validating multiple outputs, Cortensor ensures that users can trust the results, even in decentralized and untrusted setups.
* **Flexibility for Users**: Users gain the ability to choose from multiple high-quality outputs, tailoring results to their specific needs.
* **Redundancy for Quality Assurance**: Redundant task execution across miners safeguards against errors or malicious behavior, ensuring consistent output quality.
* **Scalable Validation**: PoI efficiently handles multiple outputs, maintaining system performance even as the network scales.

### Real-World Applications of Parallel Processing

* **AI-Driven Decision Support**: Multiple validated outputs allow decision-makers to evaluate different perspectives, enhancing strategic decision-making in finance, healthcare, and logistics.
* **Creative Content Generation**: Users can select the most suitable version of generated text, images, or videos, enabling tailored content creation for marketing and entertainment.
* **Data Analysis**: Parallel processing ensures consistent and reliable outputs for complex data analysis tasks, providing diverse insights from a single dataset.

### Interaction with Cortensor Modules

Parallel processing relies on Cortensor’s core modules:

* **Cognitive Module**: Orchestrates task distribution to miners and ensures that multiple outputs are generated for the same input.
* **NodeStats Module**: Tracks miner performance, helping identify reliable nodes for critical tasks.
* **Session Module**: Manages user requests, records multiple outputs, and allows users to select their preferred results.

### Technical Insights

Cortensor’s innovative approach to parallel processing transforms AI inference into a highly reliable and user-centric process. By generating and validating multiple outputs for the same input, Cortensor delivers a new level of reliability and flexibility in decentralized AI environments.

Cortensor’s unique parallel processing framework sets a new standard for decentralized AI inference, combining trust, flexibility, and scalability to meet the demands of modern AI applications.


# Embedding Vector Distance

Cortensor leverages **Embedding Vector Distance** as a core mechanism in its **Proof of Inference (PoI)** validation process. This approach ensures consistency, reliability, and trustworthiness of AI inference outputs across decentralized nodes, forming the foundation of quality assurance in the Cortensor network.

***

## **What is Embedding Vector Distance?**

Embedding vector distance refers to the mathematical measurement of similarity between two or more output vectors produced by AI models. When identical inputs are processed by the same model across multiple nodes, their outputs—despite slight variations due to computational or environmental factors—should exhibit high similarity. This similarity is quantified using techniques like cosine similarity or Euclidean distance, providing a robust method to evaluate output consistency.

***

## **How It Works in Cortensor**

1. **Input Distribution**: A predefined input (`Input A`) is sent to multiple miner nodes running identical AI models (e.g., LLaMA or LLaVA). Each node processes this input independently.
2. **Output Generation**: Each node produces an inference output based on the input and model. Due to decentralized computation and hardware variability, the outputs may slightly differ in form or structure.
3. **Embedding Creation**: The inference outputs are transformed into embedding vectors, which capture their semantic meaning in a numerical format. These embeddings are model-agnostic representations of the output content.
4. **Similarity Measurement**: Using embedding distance techniques, the system measures the similarity between the embeddings generated by different nodes. For example:
   * **Cosine Similarity**: Measures the angle between two vectors, where a value close to 1 indicates high similarity.
   * **Euclidean Distance**: Measures the straight-line distance between two vectors, where smaller values indicate higher similarity.
5. **Reliability Check**: Nodes whose outputs deviate beyond a predefined threshold (e.g., a cosine similarity score below 0.85) may be flagged for inconsistent or unreliable performance.

***

## **Why Embedding Vector Distance is Essential**

* **Ensures Consistency**: By running identical inputs across multiple nodes and measuring the similarity of outputs, Cortensor ensures consistent task execution.
* **Validates Reliability**: Embedding distance acts as a safeguard against dishonest nodes or those failing to perform properly.
* **Enhances Decentralized Trust**: In a decentralized network, embedding distance provides a quantifiable and verifiable measure of output reliability, fostering trust between miners and users.
* **Facilitates Redundancy**: By producing multiple inference variants and validating them against one another, the network can select the most reliable outputs or offer users multiple valid results.

***

## **Role in Proof of Inference (PoI)**

Embedding vector distance forms the backbone of Cortensor's **PoI validation process**:

* **Redundancy and Validation**: Nodes are tasked with the same inference job. The outputs are compared to ensure they align within acceptable similarity thresholds.
* **Consensus Formation**: A majority agreement based on embedding similarity establishes a validated inference result.
* **Cheat Detection**: Nodes producing significantly different embeddings are flagged, ensuring the network maintains high reliability and accountability.

***

## **Use Cases**

1. **Multi-Node AI Inference**: When users request AI tasks, multiple miners process the same input to ensure consistency. Embedding vector distance helps validate the outputs.
2. **Synthetic Data Validation**: For synthetic data generation, embedding similarity ensures that the produced data aligns with the expected characteristics of the input model.
3. **Quality Assurance in Training**: Developers can use embedding distances to evaluate the performance and robustness of models deployed across diverse hardware in the network.

***

## **Future Enhancements**

Embedding vector distance will evolve as Cortensor introduces **Node Reputation Systems**:

* **Time-Series Analysis**: Track node reliability over time using embedding metrics.
* **Dynamic Thresholds**: Adjust similarity thresholds dynamically based on the complexity of tasks or user-defined accuracy preferences.
* **Cross-Model Validation**: Expand embedding comparisons across different but compatible models to support heterogeneous miner nodes.

***

## **Technical Illustration**

Let’s consider an example:

* **Input**: `"What is the capital of France?"`
* **Nodes**: 5 miners running the same LLaMA model.
* **Outputs**:
  * Node 1: `"Paris is the capital of France."`
  * Node 2: `"The capital of France is Paris."`
  * Node 3: `"Paris is France's capital."`
  * Node 4: `"The capital of Paris is France."` (anomaly)
  * Node 5: `"France's capital city is Paris."`
* **Embeddings**:
  * Node 1: `[0.23, 0.11, 0.87, ...]`
  * Node 2: `[0.24, 0.10, 0.86, ...]`
  * Node 3: `[0.22, 0.12, 0.88, ...]`
  * Node 4: `[0.45, 0.32, 0.74, ...]` (outlier)
  * Node 5: `[0.21, 0.10, 0.89, ...]`
* **Similarity Scores**:
  * Nodes 1, 2, 3, 5: High similarity (\~0.95 cosine similarity)
  * Node 4: Low similarity (\~0.65 cosine similarity)

**Result**: Nodes 1, 2, 3, and 5 are validated. Node 4 is flagged as an outlier.

***

## **Conclusion**

Embedding vector distance ensures Cortensor can maintain high-quality, reliable AI inference results in an untrusted decentralized environment. By integrating this technique into PoI validation, Cortensor sets a standard for trust and accountability in decentralized AI.


# Mining Overview

Mining in Cortensor plays a critical role in maintaining the decentralized AI inference ecosystem. At its core, mining enables the processing of AI inference tasks and ensures the continuous functionality of the network. Miners contribute computational power to execute tasks such as data processing, large language model (LLM) inference, and task validation. The mining process is guided by the Proof of Useful Work (PoUW) system and Proof of Inference (PoI) to validate tasks and ensure meaningful contributions.

Even during idle periods, when there are no immediate user requests, miners are incentivized by the network to perform background tasks such as pre-emptive data generation and AI model training. This ensures that computational resources are utilized efficiently, and miners continue to earn rewards even when demand is low. Additionally, miners earn more direct rewards when serving specific user requests, where users pay for AI inference services. This dual reward system—network incentives during idle time and user payments for on-demand services—ensures a continuous flow of tasks and fair compensation for miners, keeping the network active and efficient.

### [**Proof of Useful Work (PoUW) State Machine**](/technical-architecture/consensus-and-validation/proof-of-useful-work-pouw-state-machine)

The PoUW state machine is a structured framework that governs the workflow within the network. It controls the flow of tasks through various states: Request, Create, Prepare, Start, Precommit, and Commit. The PoUW system ensures that each Miner Node is assigned tasks fairly and efficiently, while preventing dishonest behavior and ensuring timely task completion. The state machine operates with the interaction of Miner Nodes and Oracle Nodes, the latter of which monitors state transitions and requests the network to move forward if time constraints are exceeded.

### [**Proof of Inference (PoI) and PoUW**](#proof-of-inference-poi-and-pouw)

Cortensor employs PoI and PoUW mechanisms to validate the accuracy and utility of AI inference tasks. PoI ensures that the AI model's output is verified by measuring the similarity of embedding vectors, while PoUW validates the usefulness of the work performed by the miners. Together, these mechanisms ensure that miners perform valuable computations and are rewarded for legitimate, high-quality work.

### [**Miner and Oracle Node Interaction**](#miner-and-oracle-node-interaction)

In the PoUW state machine, Miner Nodes perform tasks assigned by the network, while Oracle Nodes monitor progress and request state transitions when tasks are completed or when time constraints are not met. Oracle Nodes ensure that no single point of failure occurs by requesting the reassignment of tasks to another Miner Node if the original miner fails to complete the task in time. This process maintains fairness and efficiency within the network and ensures timely task execution.

### **Mining Rewards and Incentives**

Miners in the Cortensor network are rewarded based on their contributions to the system, with rewards scaled by their performance and the importance of the tasks they complete. Even during idle periods, miners can earn rewards by processing background tasks, ensuring continuous participation and resource optimization. The Proof of Useful Work system promotes fairness in task allocation and rewards, encouraging long-term participation and innovation within the network.


# Dashboard

The Cortensor Dashboard is the central interface for observing and interacting with the decentralized Cortensor network.\
It serves simultaneously as a Mining Explorer, Node Performance Tracker, and User Interaction Layer, bridging miners, validators, developers, and end users within a unified environment.

The Dashboard provides real-time visibility into inference tasks, validator feedback, and node reliability, anchoring the operational backbone of Cortensor’s Proof of Inference (PoI) and Proof of Useful Work (PoUW) frameworks.

***

### **Purpose**

The Dashboard functions as the **operational and analytical control layer** for the Cortensor ecosystem:

* **For miners:**\
  View live task states, precommit scores, uptime history, and validator feedback.\
  Understand node reliability and performance tiers in real time.
* **For validators:**\
  Access quantitative and qualitative metrics for inference validation.\
  Observe cross-node consistency and task quality through structured reports.
* **For developers:**\
  Create, monitor, and analyze decentralized inference sessions.\
  Review payment flows, session performance, and node routing outcomes.
* **For users:**\
  Interact with Cortensor’s decentralized AI network transparently, verifying both the provenance and quality of every inference result.

The Dashboard is currently deployed across **DevNet7**, **Testnet-0**, and **Testnet-1**, providing the complete monitoring and validation interface for both L2 and L3 environments.

***

### **Key Features and Modules**

#### **1. Cognitive Tab (Mining Explorer)**

**Purpose:**\
Tracks network-assigned tasks and miner activity, visualizing validation outcomes from the PoUW framework.

**Integration:**\
Connected to the **Cognitive Module**, which runs the network task loop for node assessment and baseline capability measurement.

**Details:**

* Displays lifecycle states — **Request → Create → Prepare → Precommit → Commit**
* Includes unsupervised network task games and rounds for ongoing node evaluation
* Tracks precommit points, validator feedback, and Cognitive Level scoring
* Integrates with **QuantitativeStats (PoI)** for cross-node output similarity analysis
* Provides early visibility into **QualitativeStats (PoUW)** for usefulness scoring (in progress)

***

#### **2. NodeStats Tab (Node Performance Tracker)**

**Purpose:**\
Monitors per-node behavior, reliability, and long-term consistency across network and user tasks.

**Integration:**\
Linked to NodeStats, NodeReputation, and Validator modules to provide composite performance insight.

**Details:**

* Tracks uptime, heartbeat pings, task completion counters, and failure ratios
* Displays time-series reliability graphs from NodeReputation
* Consolidates Cognitive Level, validation feedback, and PoI results into unified node scoring
* Fully live on Testnet-1, continuously updated from Validator v2 data streams

***

#### **3. Session Tab (User Interaction Layer)**

**Purpose:**\
Provides the interface for developers and users to create, manage, and verify AI inference sessions.

**Integration:**\
Built upon Session, SessionQueue, SessionStats, and SessionPayment modules.

**Details:**

* Create sessions with configurable accuracy, correctness, and model options
* Execute decentralized inferences, with payments and deposits handled in **$COR**
* Record outputs to IPFS or decentralized storage; retain metadata on-chain
* Display validator feedback with quantitative and qualitative scoring per task
* Integrates with **Smart Job Queue** for efficient workload distribution

***

### **Active Systems and Enhancements**

#### **Node Reputation System** ✅

* Aggregates node reliability, validation, and performance data.
* Derived from NodeStats, Cognitive Level, and Validator feedback.
* Drives reputation-based routing, staking tiering, and reward adjustments.
* Fully live on Testnet-1.

***

***

#### **Enhanced Developer & User Interface** ✅

* Expanded insights for validator results, node reputation, and PoI/PoUW scoring.
* Unified routing, staking, and payment views.
* Streamlined across all environments — Testnet-0 (Arbitrum L2) and Testnet-1 (L3 COR Rollup).

***

#### **Smart Job Queue (SessionQueue Module)** ✅

* Dynamically routes workloads based on NodeSpec, Cognitive Level, and model capacity.
* Balances inference load between Cognitive and user sessions.
* Improves throughput and prevents congestion under high request volume.
* Fully operational on Testnet-1 router nodes.

***

#### **Quantitative / Qualitative Validation Stats** ⚙️

* **QuantitativeStats (PoI):** Measures embedding distance and inference similarity across nodes.\
  ✅ Foundation complete and **live** on Testnet-1.
* **QualitativeStats (PoUW):** Uses LLM-verifier models to evaluate task usefulness and coherence.\
  ⚙️ Foundation built; under active development for full rollout.
* Together they form the foundation of Cortensor’s validator intelligence layer, powering reputation and scoring models.

***

#### **Privacy-Preserving Sessions** 🚧

* Next-phase integration based on the Three-Party Encryption framework.
* Enables encrypted input/output exchange between User, Miner, and Validator without exposing data.
* Two candidate methods prototyped:
  * Combined ECDH with Commitment Sharing
  * Coordinator-Based Distribution
* Will be tested in SessionV3 during upcoming testnet iterations.
* References:
  * <https://docs.cortensor.network/technical-architecture/security-and-privacy/privacy-features-three-party-encryption>
  * <https://x.com/cortensor/status/1961173676919042383>
  * <https://x.com/cortensor/status/1960902776407646629>

***

### **Access**

* **DevNet7:** <https://dashboard-devnet7.cortensor.network/>
* **Testnet-0 (Arbitrum Sepolia):** <https://dashboard-testnet0.cortensor.network/>
* **Testnet-1 (L3 COR Rollup):** <https://dashboard-testnet1.cortensor.network/>

Each network serves a progressive role:

* **DevNet7** – Canary validation and UI iteration
* **Testnet-0** – L2 validation, session/payment integration
* **Testnet-1** – Full L3 architecture with validator-driven PoI/PoUW

***

### **Conclusion**

The Cortensor Dashboard has matured into the live command center of the decentralized inference ecosystem.\
By integrating Cognitive, NodeStats, Session, and Validator modules, it provides real-time transparency into how AI inferences are executed, validated, and rewarded.

With Quantitative PoI live, Qualitative PoUW foundation built, and Node Reputation and Smart Job Queue fully active, Cortensor’s execution fabric is verifiable and production-ready.\
The next milestone is privacy-preserving sessions, completing the loop of trust, execution, and confidentiality for decentralized AI.

As the project advances toward Testnet, the Dashboard remains the public window into Cortensor’s mission:\
to make every inference verifiable, every node accountable, and every result private by design.

***

✅ **Status:**\
Live across **DevNet7**, **Testnet-0**, and **Testnet-1**.\
Quantitative PoI operational; Qualitative PoUW foundation under active development; Privacy-Preserving Sessions next.


# Multi-Layered Blockchain Architecture

Cortensor’s **Multi-Layered Blockchain Architecture** optimizes scalability, efficiency, and security for decentralized AI inference and task processing. By leveraging distinct blockchain layers for specific roles, Cortensor provides a robust infrastructure that balances cost, speed, and adaptability.

## Layer 1 (L1): Foundational Security and Consensus

Layer 1 is the **foundation** of the Cortensor network, delivering robust security, decentralized consensus, and immutable record-keeping for critical transactions and data.

#### Example: **Ethereum**

Ethereum serves as the backbone of the system, providing trusted security, finality, and decentralized data storage for Cortensor’s core functionalities.

#### Key Functions:

* **Security Backbone**: Protects the network against attacks and tampering.
* **Consensus Mechanism**: Ensures integrity and reliability.
* **Immutable Records**: Preserves essential data and interactions permanently.

***

## Layer 2 (L2): AI Orchestration and Task Management

Layer 2 handles **AI orchestration** and **task management**, enabling efficient miner coordination and user task processing. It offloads resource-intensive operations from Layer 1 to ensure faster and more cost-effective execution.

#### Examples:

* **Base**: Acts as the “Welcome Center” for new users, offering smooth onboarding and cost-efficient registration processes.
* **Arbitrum**: Serves as the “Task & Orchestration Center,” focusing on AI task distribution, session management, and miner connections.
* **Solana**: Operates flexibly as both an orchestration hub and a user onboarding platform, leveraging its large user base and high transaction speeds for efficiency.

#### Key Functions:

* **Task Distribution**: Manages AI inference jobs efficiently.
* **Miner Coordination**: Ensures seamless miner-task assignments.
* **User Interaction Hub**: Facilitates low-cost, high-speed user interactions and onboarding.

***

## Layer 3 (L3): Privacy-Preserving and Customization

Layer 3 is designed for **privacy-preserving computations** and supports the creation of **customized chains**, making it ideal for enterprise-specific requirements. Optimized for high-throughput and confidentiality, it powers large-scale, secure AI applications.

#### Example: **Arbitrum Orbit/Optimism Superchain**

Delivers enhanced scalability and supports secure decentralized storage, enabling confidential AI inference and enterprise-grade solutions.

#### Key Functions:

* **Privacy-Preserving Computations**: Supports secure and confidential AI processes.
* **Customized Chains**: Allows tailored solutions for enterprise and industry-specific needs.
* **Advanced Scalability**: Manages high-throughput workloads for AI tasks.

***

## Why Multi-Layered Architecture?

Cortensor’s layered approach enables optimized operations for different aspects of the AI inference ecosystem:

* **L1** ensures foundational security and consensus.
* **L2** handles AI task orchestration and user interactions.
* **L3** delivers advanced privacy and scalability solutions.

By utilizing platforms such as Ethereum, Base, Arbitrum, and Solana, Cortensor provides a powerful, decentralized infrastructure designed to support diverse applications while catering to developers, enterprises, and users globally.


# Node


# Node Roles

Cortensor's decentralized AI ecosystem relies on a network of interconnected nodes, each with specific roles to ensure seamless operation and efficiency. This overview details the key roles within the Cortensor network:

### Router Nodes

**Primary Function**: Bridge users and miner nodes, managing task allocation and communication.

**Key Responsibilities**:

* Allocate AI inference tasks to appropriate miner nodes based on their capabilities.
* Ensure secure, encrypted communication between users and miners.
* Manage user sessions, including payment verification and resource allocation.
* Provide interfaces compatible with both Web2 (REST API) and Web3 (SDK).

**Critical Tasks**:

* Optimize task distribution for maximum efficiency.
* Manage session lifecycles and user interactions.
* Maintain data security and privacy through encryption.

### Miner Nodes

**Primary Function**: Execute AI inference tasks and participate in network validation.

**Key Responsibilities**:

* Perform AI inference using various models on diverse hardware (from low-end devices to high-end GPUs).
* Collaborate in task execution and result validation.
* Participate in proof of inference processes.
* Stake tokens and earn rewards based on contributions and performance.

**Critical Tasks**:

* Execute AI inference tasks efficiently.
* Validate results and ensure network accuracy.
* Build and maintain performance-based reputation.

### Clients/Users

**Primary Function**: Initiate and manage AI inference requests.

**Key Responsibilities**:

* Create and manage sessions by depositing tokens (calculated in LLM tokens).
* Submit AI inference requests via smart contracts or REST API.
* Retrieve inference results through secure channels.
* Configure validation requirements for tasks.

**Critical Tasks**:

* Manage AI inference sessions.
* Submit tasks and securely receive results.
* Balance cost and accuracy through validation configuration.

### Oracle/Master Guard Nodes

**Primary Function**: Maintain network timing and oversee block production.

**Key Responsibilities**:

* Track time and manage virtual block production.
* Ensure consistency in network operations and task execution.
* Potentially incorporate high-stakes mining responsibilities.

**Current Status and Future Plans**:

* Initially hosted by the Cortensor team.
* Plans to transition to a permissionless model or integrate with high-stake miner nodes.
* Final implementation details are still to be determined.

**Critical Tasks**:

* Maintain network synchronization.
* Oversee block timing and production.
* Contribute to network stability and reliability.

**Note**: The exact implementation of oracle/master guard nodes is subject to change as the Cortensor network evolves. The team is exploring options to further decentralize this role, potentially by integrating it with existing miner nodes or creating a new class of high-stake nodes with additional responsibilities.


# Router Node

### Purpose

This page defines what the **Cortensor Router Node** is, what it can do today, what is working in MVP form versus still being iterated, and how it fits into higher-level product surfaces such as **Bardiel** and the emerging **Portal**.

This is not only a description of a simple inference endpoint. The Router Node is increasingly the place where:

* execution
* validation
* privacy
* offchain data ownership
* session routing
* multi-session spreading
* and agent-facing workflow primitives

come together as usable API surfaces.

***

### 1. What the Router Node Is

The Cortensor Router Node is the main **execution and coordination layer** between:

* user-facing or product-facing requests, and
* the underlying Cortensor network sessions, miners, validators, privacy/data flows, and offchain storage paths

At a high level, the Router Node is responsible for translating raw network capacity into usable API surfaces.

It is the layer that currently handles, or is evolving toward handling:

* direct inference/completions
* delegated execution
* validation / grading / consensus
* privacy-aware request preparation
* offchain data flows and data ownership paths
* request/session routing
* multi-session spreading
* product-facing surfaces for apps such as Bardiel and future Portal

A useful one-paragraph summary is:

> The Cortensor Router Node is the execution and coordination layer between user-facing or product-facing requests and the underlying Cortensor network sessions. It currently supports direct completions, delegated execution, consensus-aware validation, privacy-aware request handling, offchain storage/data-ownership flows, multi-session request spreading, and integration into higher-level product surfaces such as Bardiel and the emerging Portal. It is evolving from a simple inference entry point into a broader agentic execution, trust, privacy, and coordination surface.

***

### 2. Capability Status Labels

When describing Router Node features, it is helpful to use a few consistent labels:

* **Working / in MVP form**
* **Working in rough form**
* **Implemented but still being iterated**
* **Planned / likely next**
* **Not yet part of the current router path**

These labels matter because the Router Node already does a lot today, but not every surface is equally mature.

***

### 3. Core API Surfaces

### 3.1 Direct Inference / Completions

**Current state:** Working / MVP-to-rough form

The Router Node supports direct completion/inference paths across:

* v1 completions
* v2 completions
* v3 completions

These are the simpler direct execution surfaces for standard inference requests.

#### Current capabilities

* accepts inference requests
* routes requests into configured sessions
* supports offchain / encryption-aware preparation where relevant
* supports multi-session routing for completions
* can sit behind a router pool or reverse-proxy path
* acts as the backend execution layer under hosted/product surfaces

#### Multi-session improvement

The Router now supports a newer **env-based multi-session round-robin** path for completions.

This means:

* one completion endpoint can sit on top of multiple sessions
* the Router can rotate requests across configured sessions
* explicit caller-provided session selection can still win when supplied
* v1/v2/v3 completion flows can share a cleaner session-spreading mechanism

This is important because session spreading is now part of Router behavior instead of requiring users or apps to manually rotate session IDs.

#### Current caveat

* round-robin / session spreading is still fairly basic
* this is not yet a full health-aware intelligent load balancer
* it is best understood as a first multi-session distribution mechanism, not the final one

***

### 3.2 `/delegate`

**Current state:** Working in rough-to-MVP form, still under active iteration

`/delegate` is the Router’s **execution / delegation primitive**.

It answers the question:

> “Take this task and do it for me.”

rather than:

> “Just return one model completion.”

#### Current conceptual modes

**A. Planning mode**

Used when the request is about how work should be structured rather than directly executed.

Examples:

* delegation plan
* workflow design
* routing strategy
* validation plan
* rollout plan
* incident investigation plan
* research plan
* decision / recommendation framework

**B. Execution mode**

Used when the request is:

> “Do the task and return the answer.”

Examples:

* summarize
* extract
* classify
* rewrite
* compare
* risk review
* checklist generation
* incident triage
* structured extraction
* policy / decision support
* long-text chunk / summarize / reduce
* lightweight synthesis

**C. Router-assisted execution**

Used when the Router gathers some context first and then returns the final answer.

Examples:

* fetch one URL and summarize
* fetch and extract facts
* fetch and compare
* fetch and research
* read offchain content and explain / summarize
* read safe onchain state and explain / summarize

**D. Workflow / tool mode**

If enabled, `/delegate` can use Router-side tools in a more orchestrated path.

Current tool groups mentioned in the work so far include:

* fetch/search helpers
* JSON utilities
* CSV parsing
* calculator / text utilities
* chunk / map-reduce helpers
* validation helpers
* offchain read/write
* web3 read
* reranking

#### Version direction

* v1 = earlier prompt-oriented execution primitive
* v2 = structured objective/input/execution/policy contract
* v3 = explicit redundancy and consensus-ready execution across multiple sessions
* v4 = likely future direction for more programmable trust and reusable receipts/artifacts

#### Strategic direction

`/delegate` is treated as a core primitive because it represents:

* execution outsourcing
* specialization routing
* agentic work assignment

#### Current limitations

* internal delegate logic still needed iterative refinement
* not all delegate modes are equally mature
* heavier-input and more varied tests were still being run
* one future direction is making `/delegate` behave more like a mini-agent or subset of a PyClaw-style loop

***

### 3.3 `/validate`

**Current state:** Working in rough-to-MVP form, with major consensus gaps filled

`/validate` is the Router’s **validation / grading / consensus primitive**.

It is meant to answer questions such as:

* should this result be trusted?
* how many validators agree?
* what disagreement exists?
* should we accept / retry / escalate?

#### What `/validate` is today

It is closer to:

* redundant network validation
* consensus-aware verdicting
* explicit trust judgment

rather than just a simple score.

#### v3 model

`/validate` v3 supports explicit redundancy:

* 1 validator/session path
* 3 validator/session path
* 5 validator/session path

The Router:

* selects sessions
* runs validation
* aggregates outputs
* returns a final answer plus consensus-style metadata

#### Major improvement already made

A major earlier gap was that the Router could return too early on the first committed result.

That was improved in two parts:

**Part 1 — wait for task end**

* opt-in completion/wait mode was added so the Router can wait for the task to fully end
* the Router can now pull fuller result sets instead of returning too early

**Part 2 — consensus helper**

* a Router-side consensus helper can now combine the available outputs into a final answer
* rough logic includes majority-style or aggregated verdict behavior

#### Dashboard support

Because Router-side aggregated output is not always durably preserved in the same way as raw task outputs, the dashboards also recompute a similar consensus-style summary for `/delegate` and `/validate` for viewing and debugging purposes.

#### Strategic direction

`/validate` is treated as a core primitive because it represents:

* network-native trust settlement
* explicit multi-validator verification
* decision-ready trust output for agent systems

#### Current limitations

* v3 still does not fully include an outcome loop / rework loop / evaluation event model
* this is where a likely v4 direction may borrow from stronger outcome-style validation loops
* current `/validate` is more of a consensus/judge primitive than a full “grader inside the work loop” system

***

### 3.4 `/factcheck`

**Current state:** Planned / aligned with the same family as `/validate`

`/factcheck` is repeatedly discussed as belonging to the same family/pattern as:

* `/delegate`
* `/validate`

It likely follows the same v3-style redundancy/consensus path.

It is not as deeply covered in current execution work as `/delegate` and `/validate`, but it is clearly part of the same direction.

***

### 3.5 Agent-Facing / Adapter Surfaces

Beyond the core REST endpoints, the Router Node is also evolving into a broader product and agent-facing surface.

#### Current or emerging adapter surfaces include:

* REST endpoints
* MCP server / MCP proxy layer
* x402 / pay-per-call paths on selected endpoints
* discovery / agent-card style surfaces for agent ecosystems
* backend surfaces used by Bardiel and Portal

These adapter layers matter because they make the Router more usable by:

* apps
* hosted products
* agents
* protocol-facing integrations

rather than only by direct low-level callers.

***

### 4. Completion Paths and Session Routing

Historically, the Router could:

* accept explicit session selection
* use fixed/default session logic

That remains true, but session-routing capabilities are now expanding.

### 4.1 Single-session and explicit-session paths

Single-session execution still exists and remains a valid path, especially when:

* the caller explicitly provides a session
* a product/backend layer already selected the session
* the use case wants stable single-session behavior

### 4.2 Multi-session round-robin for completions

Now implemented for completions:

* one endpoint
* multiple configured sessions
* Router-side round-robin spreading
* explicit session input can still override

This is the main current session-spreading feature in the Router itself.

### 4.3 Router-pool path

In productization / Portal V1 work, the Router increasingly sits behind:

* Nginx / reverse proxy
* router-pool grouping
* API Gateway → router pool → router node request path

This means:

* Gateway owns product/business/session-selection logic
* router pool owns healthy-router distribution
* Router Node owns actual execution

That separation is important and more precise than earlier rougher alternatives.

***

### 5. `/delegate` v3 and `/validate` v3 – Explicit Redundancy & Consensus

The v3 evolution of `/delegate` and `/validate` is important enough to call out here directly.

### 5.1 What v3 changes

v3 makes **redundancy and consensus explicit at the endpoint level**, rather than keeping them only as an internal session detail.

For these endpoints, v3 supports:

* `replicas = 1 / 3 / 5`
* `session_pool`
* `aggregation` strategy
* `disagreement_policy`

That means the Router can:

* choose 1, 3, or 5 sessions
* run the same logical task across those sessions
* gather their responses
* aggregate them into a final result plus consensus metadata

### 5.2 Why this matters

For `/delegate`:

* execution can now be spread across multiple sessions
* the Router can compare outcomes rather than just trusting one path

For `/validate`:

* validation becomes a consensus-aware judgment rather than one score from one path

For `factcheck`:

* the same 1 / 3 / 5 pattern gives a cleaner trust story

### 5.3 Current v3 rough implementation shape

A high-level v3 request concept includes:

* `replicas`
* `session_pool`
* `aggregation`
* `disagreement_policy`

The Router must:

1. select the right sessions
2. fan out the same logical request
3. gather responses
4. produce a consensus result

This is now part of the current Router direction, not just a future idea.

***

### 6. Privacy Feature 1.0

**Current state:** Working in MVP form

Privacy Feature 1.0 is a major Router-adjacent capability.

The Router is part of the path for:

* session-scope privacy / encryption
* task-scope privacy / encryption
* key retrieval / privacy-aware flows
* privacy-aware request handling

#### Current supported forms

* session-scope encryption
* task-scope encryption

#### Dedicated vs ephemeral

Privacy Feature 1.0 works across:

* dedicated nodes
* ephemeral nodes

#### Current caveat

Task-scope privacy has more UX friction on dashboard/manual inspection flows because:

* every task may require its own key retrieval/signing path

But Router-side/backend support for task-level key retrieval exists.

#### Practical significance

This is one of the main reasons the Router is no longer “just an inference endpoint.” It is part of the privacy path itself.

***

### 7. Offchain Storage v3 and Data Ownership

**Current state:** Working in MVP form

Offchain Storage v3 is the current Router-side data-ownership / offchain-storage path.

It supports:

* router-managed offchain storage references
* configurable offchain backends
* offchain inputs and outputs
* result URN handling
* deferred-write support for ephemeral nodes

### 7.1 Dedicated-node path

Dedicated-node offchain v3 flow works more directly because dedicated nodes can work with the configured storage path more cleanly.

### 7.2 Ephemeral-node path

Ephemeral nodes should not receive broad storage credentials.

So a deferred-write flow was introduced:

1. Router stores input offchain first
2. miner reads input
3. miner commits result URN
4. miner sends result content back to Router after commit
5. Router verifies assignment / auth / signature / precommit relationship
6. Router writes actual result object into offchain storage

This closed a major data-management gap in rough/MVP form.

#### Strategic significance

This is why the Router is increasingly described as handling:

* data privacy
* data ownership via Router node
* offchain result authority

not just execution.

***

### 8. Session Routing, Traffic Spreading, and Execution Distribution

The Router Node is increasingly responsible for request spreading and execution distribution.

### 8.1 Session-aware request distribution

The Router today can already:

* work with explicit session IDs
* use default sessions
* round-robin across configured completion sessions

This is the beginning of Router-side job spreading.

### 8.2 Current limitation

The current spreading path is still fairly simple:

* it is not yet a sophisticated health-aware or SLA-aware global scheduler
* it is primarily a session-spreading mechanism for completions

### 8.3 Future direction

The clear design direction is toward smarter Router-side distribution:

* better job distribution
* better session awareness
* more flexible spreading across session pools
* richer quality/SLA-aware path selection

A recurring conclusion in the work so far is:

* miner-side sequential execution is acceptable because inference is expensive and hardware-limited
* Router-side request distribution is where intelligence should improve over time

***

### 9. Router Role in Portal V1

**Current state:** Actively being productized

In Portal V1, the Router Node becomes the backend execution layer underneath:

* Portal web app
* Portal API Gateway
* router pools
* managed dedicated-backed sessions

#### Current V1 routing shape

The current direction is:

1. user calls product-facing model alias
2. API Gateway chooses the session / backend route
3. request is forwarded into the router-pool path
4. router pool distributes to healthy router nodes
5. selected Router Node executes using the already-determined session path

So the clean separation is:

* Gateway owns product/business/session-selection logic
* router pool owns healthy-router distribution
* Router Node owns actual execution

This is the important Portal role for the Router in V1.

***

### 10. Router Role in Bardiel and Other Product Surfaces

Router Nodes already back:

* Cortensor endpoints
* Bardiel endpoints
* v3 `/delegate` + `/validate` dataset generation
* Bardiel dashboard views
* ongoing heavier-input testing

This means the Router is already functioning as:

* shared execution layer
* product backend
* agent / trust surface backend

The same Router primitives are expected to underpin:

* Bardiel
* Corgent
* Portal
* future agent-facing product surfaces

***

### 11. Observability, Request Logs, and Usage Tracking

**Current state:** Working in rough form and actively being refined

At the Router side and product side more broadly, current work already covers:

* API key consumption visibility
* request tracking
* usage visibility
* logging / request-log refinement
* task lists in dashboards
* status categories such as completed / processing / stale
* consensus-style summary rendering for `/delegate` and `/validate`
* quality and node performance views

#### Still being refined

* request visibility clarity
* access logs
* usage metering polish
* per-request trace clarity
* product-facing observability cleanliness

The key point is that observability already exists in rough form and is now being shaped into something more product-usable.

***

### 12. Quality / SLA / Oracle Interaction

These are not purely “Router Node features,” but they directly affect Router/session execution surfaces.

Current quality-related direction includes:

* real periodic task probes
* actual user-style task checks
* quality stats
* quality rank tables
* node performance integration
* SLA-based filtering in node selection

This matters because the Router/session path increasingly depends on:

* better node quality selection
* better request routing under variable node reliability
* cleaner trust and SLA-aware product behavior

In other words, the Router is where backend quality signals start becoming actual execution choices.

***

### 13. Model Support Through the Router

The Router/session stack has already been extended to support newer model families, including:

* Gemma 4 variants
* Qwen 3.6 variants

These models are being used for:

* dedicated-node experiments
* eventual ephemeral-node support
* PyClaw iteration
* tool-calling quality checks
* future Portal product surfaces

This matters because the Router is the layer where those models become actually usable through sessions and endpoints.

***

### 14. Router Node Today – What Is Solid vs What Is Still Rough

### 14.1 Solid / MVP Enough Today

These are solid enough to describe as MVP-level capabilities:

* v1 / v2 / v3 completion paths
* multi-session round-robin for completions
* Privacy Feature 1.0
* Offchain Storage v3 MVP
* `/delegate` and `/validate` as usable v3 primitives
* consensus helper + task-end wait behavior for validate
* Router-backed Bardiel surfaces
* Router role in Portal baseline path

### 14.2 Rough but Working / Actively Iterated

These are working, but still actively being refined:

* richer `/delegate` workflow / tool behavior
* full `/validate` outcome-loop model
* heavier product-side logging/accounting polish
* more advanced Router-side job distribution
* router-pool + API Gateway integration polish
* large-scale performance / load behavior

### 14.3 Likely Next

Near-term likely areas of iteration:

* outcome-style validation loop on top of current `/validate`
* smarter Router-side job distribution
* more advanced multi-session and pool-level execution behavior
* stronger Portal production path
* more PyClaw-aligned Router behavior
* further productization of agent-facing and trust-facing surfaces

***

### 15. One-Paragraph Summary

The Cortensor Router Node is the execution and coordination layer between user-facing or product-facing requests and the underlying Cortensor network sessions. It currently supports direct completions, delegated execution, consensus-aware validation, privacy-aware request handling, offchain storage/data-ownership flows, multi-session request spreading, and integration into higher-level product surfaces such as Bardiel and the emerging Portal. It is evolving from a simple inference entry point into a broader agentic execution, trust, privacy, and coordination surface.


# Node Lifecycle

## From Activation to Serving Users

Cortensor's decentralized AI network relies on a structured and well-defined node lifecycle that ensures the stability, quality, and efficiency of AI inference services. This lifecycle begins with a node's entry into the network and progresses through stages of network assignments and user service.

## **1. Node Activation**

When a node operator brings their node online, the first step is to signal activation to the Cortensor network. This activation notifies the network that the node is ready to serve both network needs and user requests. Upon receiving this activation signal, the network begins to assess the node's readiness through a series of tasks designed to validate its capabilities and ensure it meets the required standards.

## **2. Network Assignment (PoI and PoUW)**

Once activated, the node undergoes a series of Proof of Inference (PoI) and Proof of Useful Work (PoUW) tasks. These tasks are crucial for maintaining the quality and reliability of the network. The assignment process involves three key types of collaboration with other nodes:

1. **Creation of Workable Blocks or Transactions:**
   * A randomly selected miner (Type 1) is tasked with creating a virtual block or transaction that other miners will collaborate on. This block serves as the foundation for subsequent tasks.
2. **Prompt and Question Generation:**
   * A second type of miner (Type 2), also randomly selected, generates detailed prompts and questions based on the initial block. These prompts are designed to guide the AI inference tasks and are agreed upon by all network nodes. The prompts are then submitted to the blockchain.
3. **Completion and Answer Generation:**
   * Multiple miners (Type 3) are then asked to generate completions based on the prompts provided by Type 2 miners. These miners must submit their outputs within a specified timeframe. Failure to meet the deadline results in penalties and a reduction in their reputation score.

This structured process ensures that nodes are not only capable of performing AI tasks but are also contributing to the network's overall health and quality control.

## **3. Transition to Ephemeral Node Status**

After successfully completing a series of network-assigned tasks, the node transitions to an "ephemeral node" status. In this state, the node is ready to serve user requests based on specific requirements. Ephemeral nodes are designed to handle short-term tasks, such as AI inference for chatbots or simple clarifications, which are tied to user-created sessions.

* **User Sessions:**
  * Users create sessions by depositing a certain amount of ETH or tokens. These sessions allow users to subscribe to AI services, specifying the model, computation, and memory requirements. Users can choose between public ephemeral nodes, which offer guaranteed metrics and performance based on reputation, or reserved nodes that prioritize privacy and dedicated resources.
* **Capacity Planning:**
  * The pre-deposit mechanism for user sessions provides economic security for node operators by allowing them to predict network capacity needs and plan their operations accordingly. The total number of session deposits correlates with the network capacity required to support all user requests.

## **4. Ongoing Network Assignments and Quality Control**

Even after becoming an ephemeral node, the node continues to receive PoI and PoUW tasks as part of ongoing network sampling. This continuous quality control process ensures that nodes maintain high standards and remain reliable for user requests. If a node fails to complete these tasks, its reputation score will be penalized, which can impact future network assignments and user payments.

## **5. Node Deactivation**

Node operators can temporarily deactivate their nodes for maintenance or other reasons without affecting their reputation. By opting out of network assignments and PoI/PoUW tasks through a simple CLI command, they avoid penalties and can rejoin the network when ready.

## Conclusion

Cortensor's node lifecycle—from activation and network assignments to serving user requests—ensures a robust and reliable decentralized AI network. The structured approach, combining gamified quality control and dynamic role allocation, makes Cortensor unique and predictable in delivering AI inference services. By adhering to this lifecycle, node operators can maximize their contributions to the network while earning rewards and maintaining a strong reputation.


# Ephemeral Node State

Ephemeral Node State refers to a temporary and dynamic status assigned to nodes that have successfully passed cognitive validation and are ready to serve user tasks. Unlike static or permanently assigned nodes, ephemeral nodes are part of a pool that ensures flexibility and optimal resource allocation.

## **How It Works:**

1. **Validation:** Nodes must pass cognitive tests to ensure they meet quality standards for AI inference.
2. **Availability:** Once validated, nodes enter the ephemeral state, meaning they are on standby, ready to take on user tasks.
3. **Session Assignment:** When a task is allocated from the session queue, an ephemeral node is temporarily assigned and marked as "reserved."
4. **Release & Revalidation:** After completing the session, the node is released back to the ephemeral pool but must undergo another cognitive validation before being reassigned.

## **Why It Matters:**

* **Ensures High-Quality Inference:** Continuous validation prevents degraded performance.
* **Optimizes Resource Allocation:** Nodes are dynamically assigned based on real-time demand.
* **Improves Network Efficiency:** Reduces idle time and maximizes utilization of available computing power.

By maintaining an **Ephemeral Node Pool**, Cortensor ensures only high-performing, validated nodes participate in AI inference, maintaining network reliability and efficiency.


# Node Reputation

Node Reputation is an essential extension of Cortensor's NodeStats module, designed to enhance trust and reliability across the decentralized AI network. While NodeStats records real-time metrics like counters and points for task participation, Node Reputation captures the temporal dimension of these metrics, transforming them into a comprehensive time-series dataset.

## **Integration with NodeStats and Cognitive Module**

* **NodeStats Recording**: The NodeStats module captures key metrics, such as task counters (number of tasks entered) and points (success or failure outcomes). These provide a snapshot of node activity and performance.
* **Cognitive Module Role**: When a node successfully completes a task, the Cognitive module communicates with Node Reputation to log the timestamp of this success. This allows the network to track not just the quantity but also the timing and consistency of node performance over time.
* **Time-Series Metrics**: Node Reputation aggregates these timestamps, creating a longitudinal dataset that reflects how often and how reliably nodes succeed in their assigned tasks.

## **Key Features and Functionality**

* **Ephemeral Status Assignment**: Nodes that consistently demonstrate success over time through their time-series metrics can achieve ephemeral status. This qualifies them for user-defined tasks via the Session and SessionQueue modules.
* **Dynamic Updates**: Unlike static snapshot metrics, time-series tracking allows for the dynamic assessment of node performance, enabling the network to adapt to changing node behaviors and capabilities.
* **Quality Assurance**: By continuously evaluating the success timestamps from Cognitive module interactions, Node Reputation ensures nodes meet predefined reliability thresholds.

## **Implementation Workflow**

1. **Task Completion**: A node completes a task assigned by the Cognitive module.
2. **Timestamp Logging**: The Cognitive module records the success and triggers Node Reputation to log the corresponding timestamp.
3. **Data Aggregation**: Node Reputation aggregates these timestamps into a time-series dataset.
4. **Ephemeral Status Transition**: Nodes meeting predefined thresholds of reliability and frequency gain ephemeral status, making them eligible for higher-tier user tasks.
5. **Periodic Evaluation**: Ephemeral nodes continue to be assessed through ongoing timestamp logging and threshold checks.

## **Future Enhancements**

* **Granular Analysis**: Implementing per-node instances of Node Reputation for more detailed evaluations.
* **Expanded Metrics**: Tracking additional parameters, such as task complexity and latency, to further refine node reputation scores.
* **Dynamic Thresholds**: Introducing adaptive thresholds based on network demands and evolving task requirements.

## **Impact on Cortensor Ecosystem**

By integrating Node Reputation with NodeStats and the Cognitive module, Cortensor ensures:

* **Reliability**: Nodes are assessed continuously for performance, enhancing trust in the network.
* **Efficiency**: Time-series data helps identify the most capable nodes for specific tasks, optimizing resource allocation.
* **Scalability**: Dynamic assessments allow the network to scale efficiently while maintaining high performance and quality standards.

Node Reputation transforms simple task success metrics into a robust, temporal evaluation system, ensuring Cortensor’s decentralized AI network operates reliably and efficiently.


# User Interaction & Node Communication

In the Cortensor network, three primary node roles work together to facilitate AI inference tasks: **Client Nodes**, **Router Nodes**, and **Miner Nodes**. These roles interact seamlessly to ensure decentralized, efficient, and scalable AI service delivery. Below is an explanation of how communication and user-serving workflows operate within this architecture.

## **Node Roles Overview**

1. **Client Nodes**: Client nodes represent users or applications (web2 or web3) that initiate AI tasks by interacting with the Cortensor network. These nodes can be embedded into an application to provide AI features, and they primarily communicate with the **Router Nodes** and smart contracts. Client nodes can bypass router nodes and interact directly with miners and the smart contract if needed, but utilizing router nodes enhances the user experience by optimizing communication and integration with the network's full features.
2. **Router Nodes**: Router nodes act as intermediaries between client nodes and miner nodes. They handle various protocols and interfaces, including:

   * **REST API, REST API Stream, and WebSocket** for web2 clients to offer smooth communication channels.
   * **Smart contracts and decentralized storage protocols like IPFS** for web3 clients, enabling decentralized interaction and result storage.
   * Relaying requests and responses between miners and clients in real-time, ensuring seamless communication.
   * Streaming responses back to client nodes, mimicking behavior like OpenAI’s LLM streaming responses for enhanced user interaction.
   * Authorizing client and miner nodes within the network via smart contracts.
   * Managing the reputation of miners based on their task execution, token speeds, and accuracy.

   Router nodes also validate and forward miners' responses to clients, ensuring the network's integrity and timeliness while handling various protocols.
3. **Miner Nodes**: Miner nodes are responsible for performing AI inference tasks. When selected by the network, these nodes execute tasks such as large language model (LLM) inference or data processing. Miners are rewarded for completing tasks based on network demand and user requirements.

## **Flow of Operations**

### **1. Session Creation**

The process begins when a **client node** creates a session. A session is essentially a contract between the client and the network, specifying the AI task configuration, including which model to use, the required correctness, and the validation mechanisms. The client must deposit **$COR** tokens into the network, which are deducted as they utilize services. This deposit model helps predict network capacity requirements and allows for dynamic pricing in the future.

### **2. Task Request**

Once a session is created, the **client node** sends a request to the smart contract. The smart contract, in turn, informs a **router node**, which consumes the task and assigns it to qualified **miner nodes**. Router nodes act as job schedulers, selecting miners based on predefined criteria, such as miner performance and reputation. Miners may be dedicated to the session, or selected randomly as ephemeral miners for short-term assignments.

### **3. Session Queue and Task Assignment**

Router nodes maintain a session queue to manage task distribution. Miners either consume tasks from this queue on a first-come-first-serve basis, or they may be pre-assigned to specific sessions. If the client requests a higher level of correctness or redundancy, multiple miners may work on the same task to ensure accuracy. In such cases, several miners perform the same task, and their results are compared using methods such as **embedding vector distance** to identify discrepancies and ensure no miners are behaving dishonestly.

### **4. Mining and Task Execution**

Miner nodes perform the actual AI inference, such as running LLM completions based on the client’s input and configuration. For complex tasks, miners may need to coordinate their efforts across multiple steps or phases, using the **Proof of Useful Work (PoUW)** state machine to track progress and ensure that all tasks are completed correctly and on time. If a miner fails to respond within a given period, an **Oracle node** requests the smart contract to assign the task to a different miner.

### **5. Precommit and Commit Phases**

During the task execution, multiple miners may participate in the **precommit** and **commit** phases. In the precommit phase, miners submit a hash of their work to prevent dishonest behavior. During the commit phase, miners reveal their actual results, which are compared against each other to ensure consistency.

### **6. Result Submission and Validation**

Once miners complete the task, the results are submitted back to the smart contract and stored on decentralized storage such as IPFS. These results are also streamed back to the **router node**, which relays them to the client node in real-time (optional, similar to OpenAI's streaming response). Validation of the task results occurs through a process similar to PoUW, where validators (or additional miners) use embedding vectors to compare results and ensure the task was performed correctly.

### **Mining and Network Incentives**

Miners earn rewards by processing AI tasks. These rewards are based on task complexity, timeliness, and accuracy. Even during idle times, miners can perform background tasks and earn network rewards. This dual reward structure, consisting of network incentives and direct payments from user requests, ensures continuous participation from miner nodes.

### **Future Expansion**

The framework described here can be extended to support more complex use cases, such as **synthetic data generation** and enhanced AI tasks. As Cortensor evolves, the Proof of Useful Work (PoUW) system will accommodate a broader range of AI-driven tasks, cementing its role as a decentralized AI job scheduler.

***

In summary, Cortensor's node communication and user-serving architecture is designed for scalability, flexibility, and decentralization. The seamless interaction between client nodes, router nodes, and miner nodes ensures efficient AI task execution, while smart contracts and PoUW mechanisms provide robust validation and incentives for network participants. The router nodes' ability to handle multiple communication protocols further enhances their role as a bridge between clients and miners.


# Session, Session Queue, Router, and Miner in Cortensor

Cortensor’s modular architecture is designed to facilitate efficient AI inference processing through a **microservices-inspired structure**, where each module acts as a **mediator between two or more parties**. This ensures **scalability, reliability, and modular communication** within the decentralized AI network.

Each module:

* Stores only **necessary datasets**, reducing data redundancy.
* **Relies on other modules** to fetch relevant data through function calls.
* Facilitates **seamless communication** between different network components.

#### **Examples of Module Interactions**

* **Cognitive Module** – Manages interactions between oracle nodes and miners to maintain network health.
* **Node Stats & Reputation Module** – Tracks performance and reliability of miners by directly gathering real-time data from miners, while oracle nodes assist in coordination and timing measurement.
* **Node Pool Module** – Maintains the state of available miner nodes, updating data through interactions with the node reputation module and node pool agents.

Now, let’s dive into the **Session and Session Queue modules**, which are primarily responsible for **serving user requests efficiently**.

***

### **Session & Session Queue: Serving User Requests**

The **Session Module and Session Queue** are central components in Cortensor that **handle AI inference requests from users**. They are designed to ensure optimal **task assignment, execution, and data integrity**.

#### **Module Interactions**

* **Router Node ↔ Client** → Handles user interactions, relays requests, and returns responses.
* **Session Module ↔ Router Node** → Manages user session creation and request handling.
* **Session Module ↔ Session Queue Module** → Facilitates task queuing and miner assignment.
* **Session Queue Module ↔ Miners** → Allocates jobs to miners, manages task execution, and ensures balanced workload distribution.
* **Session Queue Module ↔ Router Node** → Receives inference results from miners and forwards them back to the Router Node for client delivery.

#### **User Request Flow in Cortensor**

The **Session Module** plays a vital role in creating and managing AI inference sessions. Below is the **rough workflow** of how Cortensor handles user requests:

1. **Session Creation**
   * A **user initiates a session** through a **router node**.
   * The **router node forwards the session request** to the **Session Module**.
2. **Node Selection & Reservation**
   * The **Session Module queries the Node Pool** to find **available ephemeral nodes**.
   * **Selected nodes are reserved** in the **Session Queue** for the session.
3. **User Request Processing Begins**
   * Once a session is **fully assigned**, it is ready to process **inference requests**.
4. **User Submits Inference Request**
   * The user sends a **request via the Router Node** (either through **REST API** or directly via **smart contract**).
   * The **Router Node relays the request** to the **Session Module**.
5. **Task Assignment & Dispatch**
   * The **Session Module forwards the request** to the **Session Queue**.
   * The **Session Queue dispatches tasks** to the **miners** assigned to that session.
6. **Event Emission for Miners**
   * The **Session Module emits task events**, notifying miners in the session.
   * **Miners listen** to these events and begin working on the **inference request**.
7. **Miners Process & Relay Inference Data**
   * Miners execute inference and **stream results per token processed**.
   * **WebSockets relay the inference data** to the **Router Node**.
   * The **Router Node forwards the processed response** to the **Client SDK** through **REST Streaming or WebSockets**.

#### **Data Integrity & Validation**

To ensure **reliable inference data**, miners **commit their results in two steps**, similar to the **Cognitive Module’s state machine validation process**.

8. **Precommit Stage**
   * Miners **generate a hash** of the inference data and submit it.
   * This ensures **commitment without exposing the actual inference result**.
9. **Commit Stage**
   * Miners **submit the actual inference data** to the **Session Queue**.
   * The **Session Queue validates** the inference data before marking it as **finalized**.

***

### **Node Pool & Ephemeral Node State**

The **Node Pool** is responsible for managing **ephemeral state miners**—nodes that are available for AI inference tasks.

* **Ephemeral State**: A node **enters the ephemeral state** once it has passed **Cognitive Module validation** and is **ready to serve inference tasks**.
* **Session Assignment**: When a **session is created**, the **Session Module selects ephemeral nodes** from the **Node Pool**.
* **Node Marking & Release**:
  * **When a node is assigned** to a session, it is marked as **reserved**.
  * **Once the session is completed**, the node is **re-tested by the Cognitive Module** before being returned to the **ephemeral pool**.

This mechanism ensures **only high-quality nodes** serve user requests, maintaining **performance integrity** across the network.

***

### **Current Design & Future Considerations**

#### **Current State**

* **Session & Session Queue handle AI inference requests.**
* **Ephemeral Nodes dynamically serve user requests** with built-in integrity checks.
* **Router Nodes manage user interactions** and relay responses efficiently.

#### **Future Enhancements**

* **TBA**

***

### **Conclusion**

The **Session Module, Session Queue, Router, and Miner nodes** form the backbone of **Cortensor’s decentralized AI inference framework**. Through **modular interactions, real-time event processing, and a secure validation system**, Cortensor ensures **scalable, efficient, and reliable AI inference** while maintaining **network integrity**.


# Network & Flow

Cortensor's network architecture is designed to facilitate seamless interaction between different node types, ensuring efficient task execution and robust AI inferencing capabilities. This section provides a detailed overview of the network flow, illustrating how various components interact to deliver high-quality AI services.

**Overview**

The Cortensor network consists of several key components, each playing a specific role in maintaining the system's integrity, efficiency, and scalability. The network flow encompasses the processes from session creation to task completion and validation, ensuring a seamless user experience.

### **Network Components**

**Router Nodes**:

* Act as intermediaries between users and miner nodes.
* Manage task allocation, session creation, and secure communication.
* Provide compatibility with Web2 (REST API) and Web3 (SDK) environments.

**Miner Nodes**:

* Perform AI inferencing tasks using various AI models.
* Range from low-end devices to high-end GPUs, ensuring inclusivity.
* Participate in validation processes to ensure result accuracy.

**Clients/Users**:

* Initiate sessions and submit AI inference requests.
* Interact with the network through smart contracts or REST API.
* Retrieve results and configure validation levels.

**Oracle/Master Guard Nodes**:

* Maintain block time consistency and validate tasks.
* Operate in a permissioned setting, transitioning to permissionless in the future.
* Govern network operations and ensure reliability.

### **Network Flow**

**Session Creation**:

* Users create a session by depositing tokens, calculated in terms of LLM tokens.
* The session represents a subscription where users allocate assets for using AI inference services.

**Prompt Submission**:

* Users submit prompts to the network via smart contracts or REST API through router nodes.
* The router node verifies payment and other session parameters before processing the request.

**Task Allocation**:

* Router nodes analyze incoming requests and allocate tasks to the most suitable miner nodes based on their capabilities.
* The allocation process considers the type of model to be used, the node's performance, and the required response time.

**Task Execution**:

* Miner nodes perform the assigned AI inference tasks.
* Tasks are executed according to the specified model and parameters.
* Miners submit the results securely, ensuring data integrity and privacy.

**Result Validation**:

* Validation nodes or other miner nodes validate the results to ensure accuracy.
* Validation can be configured by the user during session creation, allowing for varying levels of thoroughness and cost.
* Validation methods include semantic checks, embedding comparisons, and checksum verifications.

**Result Retrieval**:

* Once validated, results are delivered to the user through smart contracts, REST API, or WebSocket.
* The router node facilitates the secure transmission of results, maintaining user privacy and data security.

**Incentive Distribution**:

* Miners and validators receive rewards based on their contributions to the network.
* Rewards are distributed in tokens, incentivizing participation and ensuring network stability.

### **Key Processes**

**Dynamic Task Matching**:

* The router node dynamically matches inference requests to the capabilities of miner nodes.
* This process optimizes resource utilization and ensures timely task completion.

**Proof of Inference (PoI)**:

* A consensus mechanism that validates task completion and ensures the reliability of AI inference.
* Involves collaborative efforts among nodes to complete and validate tasks, building a reputation system based on performance.
* Validates the similarity of completion among other inference nodes using the same model, measured by embeddings and vector distances to ensure nodes have performed the task correctly.

**Proof of Useful Work (PoUW)**:

* Ensures the correctness and usefulness of AI inference results.
* Validates whether the generated information is useful and extendable as knowledge.
* Involves additional checks such as semantic consistency, logical coherence, or practical applicability.
* Validators provide feedback or scores on the results, helping to determine their usefulness.

**Security and Privacy**:

* Data transmission within the network is encrypted to maintain privacy.
* Nodes stake tokens to participate, ensuring commitment and reducing the likelihood of malicious behavior.


# Coordination & Orchestration

Cortensor's decentralized AI network relies on sophisticated coordination and orchestration mechanisms to ensure efficient task management, optimal resource utilization, and seamless integration of various node types. This section outlines the key processes that enable effective coordination and orchestration within the Cortensor ecosystem.

**Overview**

Cortensor's coordination and orchestration framework manages dynamic interactions between nodes, optimizes task allocation, and ensures timely execution of AI inference tasks. By leveraging advanced algorithms and decentralized protocols, Cortensor maintains a balanced, efficient, and scalable network.

### **Key Components**

1. **Dynamic Task Allocation**
   * **Intelligent Routing**: Router nodes dynamically allocate tasks to miner nodes based on real-time assessment of node capabilities and task requirements.
   * **Multi-factor Optimization**: Allocation algorithms consider node performance, current workload, task complexity, and user-defined parameters to optimize resource utilization.
   * **Load Balancing**: Ensures even distribution of tasks across the network, preventing bottlenecks and maximizing overall efficiency.
2. **Session Management**
   * **User-defined Sessions**: Users create sessions that define the scope, requirements, and parameters of their AI inference tasks.
   * **Lifecycle Management**: Router nodes oversee the entire lifecycle of sessions, from initiation to completion and result delivery.
   * **Integrated Payment System**: Sessions include provisions for token-based payments, ensuring fair compensation for network resources.
3. **Task Segmentation and Distribution**
   * **Adaptive Segmentation**: Complex AI inference tasks are intelligently segmented into smaller subtasks based on their nature and complexity.
   * **Parallel Processing**: Subtasks are distributed across multiple miner nodes, enabling parallel processing and faster task completion.
   * **Dynamic Reassignment**: In case of node failures or performance issues, tasks are automatically reassigned to maintain continuity.

### **Orchestration Processes**

1. **Collaborative Task Execution**
   * **Multi-stage Processing**: Tasks are executed in structured stages, with different nodes handling specific parts of the inference process.
   * **Inter-node Communication**: Secure protocols enable efficient communication between nodes involved in a single task.
   * **Result Aggregation**: Final results are compiled from multiple nodes' outputs, ensuring comprehensive and accurate inference.
2. **Proof of Inference (PoI)**
   * **Consensus Mechanism**: A novel approach to validating the completion and accuracy of AI inference tasks.
   * **Multi-node Validation**: Involves multiple guard nodes in the validation process, using semantic checks, embedding comparisons, and checksum verifications.
   * **Fraud Prevention**: Robust validation processes detect and prevent malicious activities, ensuring network integrity.
3. **Proof of Useful Work (PoUW)**
   * **Correctness Validation**: Ensures the correctness and practical usefulness of AI inference results.
   * **Utility Verification**: Validators assess whether the generated information is useful and extendable as knowledge.
   * **Feedback System**: Validators provide feedback or scores on the results, helping to determine their usefulness and ensuring continuous improvement.
4. **Reputation and Scoring System**
   * **Performance-based Reputation**: Nodes build reputation scores based on their task execution quality, validation accuracy, and overall reliability.
   * **Dynamic Task Allocation**: Higher-scoring nodes receive more complex tasks and increased rewards, incentivizing consistent high-quality performance.
   * **Continuous Evaluation**: Node reputation is continuously updated, ensuring the system adapts to changing node capabilities and network conditions.

### **Advanced Features**

1. **Adaptive Privacy Layers**
   * **L2/L3 Chain Integration**: Utilizes layer 2 and layer 3 blockchain solutions for enhanced privacy and scalability.
   * **Encrypted Task Execution**: Offers options for encrypted prompts and completions on privacy-sensitive tasks.
2. **AI Model Marketplace**
   * **Decentralized Model Repository**: Facilitates the exchange and deployment of AI models within the network.
   * **Model Versioning**: Manages different versions of AI models, ensuring compatibility and optimal performance.
3. **Real-time Network Analytics**
   * **Performance Monitoring**: Continuous monitoring of network health, node performance, and task execution metrics.
   * **Predictive Optimization**: Uses AI-driven analytics to predict network demands and optimize resource allocation proactively.


# Multi-Oracle Node Reliability & Leadership Rotation

To enhance the reliability and fault tolerance of Cortensor’s oracle infrastructure, a phased approach is being adopted to transition from a single-oracle setup to a distributed and resilient oracle cluster model. This will reduce downtime risks caused by unstable RPC endpoints or stalled oracle nodes.

## Phase 1: Off-Chain Rotation via NTP-Based Logical Coordination

**Overview**\
In the initial phase, leadership among multiple oracle nodes is managed off-chain using synchronized NTP timestamps and logical rules.

### **Mechanism**

* All oracle nodes maintain a synchronized clock using NTP.
* A round-robin rotation schedule determines which node is active leader during a given time window.
* The current leader is responsible for executing critical oracle tasks (e.g., triggering Cognitive tasks, session updates).
* If the leader becomes unresponsive or exceeds its window:
  * The next designated oracle takes over automatically.
  * Leadership changes are based on elapsed time and session activity checks.

### **Advantages**

* Simple and fast to implement.
* Enables automated fallback and basic fault tolerance without requiring contract-level changes.
* Effective during early-stage deployment with low consensus overhead.

***

## Phase 2: On-Chain Coordination via Smart Contract Timestamping

**Overview**\
In the second phase, oracle coordination will be enforced and recorded on-chain, increasing transparency and trustlessness.

### **Mechanism**

* Oracle nodes submit heartbeat or activity proofs (e.g., session commits) to a smart contract.
* The smart contract tracks:
  * The active oracle node.
  * Timestamp of last valid action.
* If a node fails to perform its duties within the expected timeframe:
  * The contract automatically emits a leadership rotation event.
  * The next oracle is granted active status based on a predefined sequence or dynamic reputation.

### **Advantages**

* Trustless and verifiable oracle activity.
* Tamper-proof and permissionless failover logic.
* Lays the foundation for fully decentralized oracle clusters with on-chain accountability.

***

## Summary

| Phase | Coordination Method       | Failover Trigger                | Transparency | Implementation Complexity |
| ----- | ------------------------- | ------------------------------- | ------------ | ------------------------- |
| 1     | NTP-based + Logical Logic | Time window + session check     | Low          | Low                       |
| 2     | Smart contract-based      | On-chain timestamp & inactivity | High         | Medium–High               |

Together, these phases enable a graceful evolution from centralized coordination to decentralized resilience—ensuring Cortensor’s oracle infrastructure scales securely and reliably.


# Data Management

Cortensor employs a sophisticated multi-layered blockchain architecture to efficiently manage coordination, quality assurance, and user services. This approach ensures robust, scalable operations while maintaining data integrity and optimizing costs.

## **Multi-Layer Blockchain Structure**

1. **Registration and Onboarding Layer**
   * **Technology**: Ethereum or Layer 2 solutions (Arbitrum, Base, Optimism)
   * **Purpose**: Handles the secure registration and onboarding of miners and users
   * **Benefits**: Ensures a trustworthy foundation for network participation
2. **Health and Capability Verification Layer**
   * **Technology**: Layer 2 chains
   * **Purpose**: Monitors miner health and capabilities through Proof of Inference (PoI) and Proof of Useful Work (PoUW) mechanisms
   * **Key Features**:
     * Real-time performance monitoring
     * Dynamic capability assessment
     * Ensures miners meet and maintain required standards
3. **User Interaction and Service Layer**
   * **Technology**: Layer 2 or Layer 3 chains
   * **Purpose**: Facilitates dApp interactions and access to Cortensor's inference and oracle services
   * **Current Offering**: API layer for inference services
   * **Future Plans**: Advanced SDKs and libraries for specialized tasks (e.g., classification, data generation)

## **Data Storage and Communication Strategy**

### **Off-Chain Data Management**

* **Technology**: IPFS (InterPlanetary File System)
* **Purpose**: Decentralized storage of prompts, requests, completions, and results
* **Benefits**:
  * Cost-effective storage solution
  * Maintains data integrity and accessibility
  * Reduces blockchain bloat

### **Router Node Communication**

* **Capabilities**:
  * Handles Web2 traffic seamlessly
  * Interfaces with Layer 2 and Layer 3 blockchain layers
* **Function**: Ensures secure, efficient data transmission between users and the network

### **Data Encryption**

* **Purpose**: Protects user data privacy by encrypting communications between node types
* **Flexibility**: Encryption can be tailored based on user preferences to balance security and performance

### **User Data Integration**

* **Current Feature**: On-demand data persistence to external databases
* **Future Development**:
  * Integration of user databases, documents, vectors, and embeddings into inference requests
  * Enhanced support for smarter application integration

## **Key Components and Future Roadmap**

### **Blockchain Layer Utilization**

* **Ethereum/Layer 2 for Onboarding**
  * Secure, transparent registration process
  * Foundation for trust in the network
* **Layer 2 for Health Checks**
  * Continuous monitoring and assessment of miner capabilities
  * Ensures network reliability and performance standards
* **Layer 2/Layer 3 for Services**
  * Scalable infrastructure for dApps and user services
  * Facilitates efficient access to inference and oracle functionalities

### **Off-Chain Storage Innovation**

* **IPFS Integration**:
  * Decentralized, resilient data storage
  * Cost-effective solution for handling large volumes of inference data
  * **Data Integrity**: Ensures immutability and accessibility of stored information

### **Future Enhancements**

* **Advanced Data Integration**:
  * Support for client-side data hosting
  * Seamless integration of user databases and data sources into Cortensor's inference services
* **Enhanced SDK Development**:
  * Specialized tools for complex AI tasks
  * Simplified integration process for developers


# Private / Encrypted Inference

> Draft / WIP – this document captures the current plan for private / encrypted inference on Cortensor, starting with dedicated sessions and evolving toward SDK-native Web3 flows and, ultimately, TEE-backed confidential execution.
>
> It complements the main architecture docs:
>
> * Technical: `technical-architecture/data-management/private-encrypted-inference`
> * Phase roadmap: `roadmap/testnet-phase-3`

***

### 1. Goals & Scope

The private / encrypted inference roadmap is designed to:

* Let users encrypt prompts and results end-to-end for selected workflows.
* Keep router & miners blind to plaintext wherever possible, while still routing correctly.
* Start with config-driven dedicated sessions and gradually extend to:
  * Ephemeral / pooled nodes (dynamic assignment)
  * A unified key-issuance engine
  * SDK-native Web3 integration (wallet-based auth + policy)
  * TEE-backed confidential execution (Nitro / TDX) as the highest-assurance mode

We talk about “versions” in terms of the privacy/key system, not the router API:

* **V0** – dedicated sessions, router-managed allowlist + key derivation (env-based).
* **V0.5** – move allowlist to onchain contract, router becomes contract-enforced.
* **V1** – ephemeral / pooled node support (assignment-aware keys).
* **V2** – unified engine for all session types (pluggable policies).
* **V3** – SDK-native Web3 private inference (wallet + policy).
* **V4** – TEE-backed private inference (Nitro / TDX nodes as final privacy layer).

All versions assume **offchain payload v2** for encrypted content (so rotation/backfill is possible).

***

### 2. V0 – Dedicated Sessions, Router-Managed Policy & Key Issuance

#### 2.1 What V0 Supports

V0 focuses on **dedicated-node sessions** where the router knows the full path (User ↔ Router ↔ Miner) and can safely manage encryption keys.

New auth endpoints (concept):

* `POST /api/v1/auth/payload_enc_key/session`\
  → issue a session-level encryption key derived from `session_id`.
* `POST /api/v1/auth/payload_enc_key/task`\
  → issue a task-level encryption key derived from `session_id + task_id`.

Auth flow:

1. Caller sends:
   * `address` (EOA)
   * `signature` over canonical scope string
   * `scope` fields:
     * Session endpoint signs the string: `"session_id"`
     * Task endpoint signs the string: `"session_id:task_id"`
2. Router:
   * Verifies the signature with `verify_addr_str_message(scope_string)`.
   * Checks `address` against `ENCRYPTION_ALLOWED_LIST` (V0 policy source).
   * If authorized, derives a `payload_enc_key` deterministically from:
     * `ENCRYPTION_SEED`
     * Scope (for example `"101"` or `"101:9001"`).
3. Router returns:
   * `payload_enc_key` (or a wrapped form)
   * `scope` / `scope_type` (session or task)
   * `key_version` (see keyring below)

Apps use this key to encrypt/decrypt payloads client-side; the router only sees encrypted blobs + metadata and routes them like any other payload.

#### 2.2 Deterministic Key Derivation

Current prototype (short-term acceptable):

* `payload_key = SHA256(ENCRYPTION_SEED + ":" + scope)`

Longer term, prefer **HKDF** with explicit versioning:

* `payload_key_vN = HKDF(seed_vN, info = "cts:v0:" + scope)`

Key properties:

* Deterministic for the router (given seed + scope).
* Not guessable from `session_id` / `task_id` alone.
* Security depends on strength of `ENCRYPTION_SEED_vN`:
  * Use at least 32 bytes of high-entropy random.
  * Rotate if exposed or suspected compromised.

#### 2.3 Encrypted Payload Metadata (Offchain v2)

Encrypted payloads follow an offchain payload v2 pattern with explicit metadata, for example:

```
{
  "alg": "aes-256-gcm",
  "scope_type": "session",      // or "task"
  "session_id": 101,
  "task_id": 9001,
  "key_version": "v3",
  "nonce": "base64-encoded",
  "tag": "base64-encoded",
  "ciphertext": "base64-encoded",
  "created_at": "2026-03-01T12:34:56Z"
}
```

Rules:

* Router does not see plaintext; it only uses:
  * `session_id` / `task_id`
  * `scope_type`
  * `key_version`
* All encrypted prompts/results must use this v2 metadata format.
* Plaintext may be kept separately only in trusted tooling during backfill/rotation.

***

### 3. V0 Key Rotation Model (Critical)

We must never run the network on a single long-lived seed.

#### 3.1 Keyring Model

Router keeps a **keyring**:

* `active_version = vN`
* `legacy_versions = [vN-1, vN-2, ...]` (decrypt-only)

Behavior:

* Issuance:
  * `/auth/payload_enc_key/*` always derives keys with active `ENCRYPTION_SEED_vN`.
  * Response includes `key_version = "vN"`.
* Encryption client-side:
  * Clients persist `key_version` inside the encrypted payload metadata.
* Decryption:
  * Router first uses `key_version` from metadata.
  * Only if needed, fall back to range mapping or legacy assumptions for migration.

#### 3.2 Backfill & Retirement

For offchain v2 payloads:

1. Background worker:
   * Reads ciphertext with legacy `key_version`.
   * Decrypts using the corresponding legacy seed.
   * Re-encrypts with active seed/version.
   * Updates stored payload + metadata in-place, so **the offchain payload URN/ID stays the same**.
2. Once SLO window passes and backfill coverage is acceptable:
   * Mark old versions as retired (no decrypt).
   * Optionally purge old ciphertexts or mark them invalid.

#### 3.3 If a Seed is Stolen

If `ENCRYPTION_SEED_vK` is compromised:

* Assume ciphertexts under that version are compromised if attacker can access them.
* Immediate steps:
  * Rotate `active_version` to `vK+1`.
  * Stop issuing keys for `vK`.
  * Revoke affected sessions/leases as needed.
* Recovery options:
  * For offchain v2 payloads:
    * Re-encrypt from trusted source data, or
    * Re-encrypt from ciphertexts decryptable with known-good key material.
  * For onchain:
    * Only store policy + references, never raw secrets or seeds.

***

### 4. V0 Policy – ENCRYPTION\_ALLOWED\_LIST (Dedicated Sessions)

#### 4.1 Env Format

V0 uses an env-based allowlist to control which addresses can request keys for which scopes:

```
ENCRYPTION_SEED="replace-with-strong-random-seed"
ENCRYPTION_ALLOWED_LIST="101:0x1111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222;102:0x3333333333333333333333333333333333333333;101-9001:0x4444444444444444444444444444444444444444,0x5555555555555555555555555555555555555555;202-77:0x6666666666666666666666666666666666666666"
```

Semantics:

* `session_id:addr,addr` → session-level allowlist.
  * Example: `101:0x11...,0x22...` → addresses allowed for session `101`.
* `session_id-task_id:addr,addr` → task-level allowlist.
  * Example: `101-9001:0x44...,0x55...` → addresses allowed for session `101`, task `9001`.

Rules:

* No spaces; addresses must be `0x` + 40 hex chars.
* Router parses this once and uses it to grant/deny key issuance.

This is V0 only and intended for **dedicated-node sessions** where operator and app are known/trusted.

***

### 5. V0.5 – Contract-Backed Allowlist

To move beyond static env-based policy, we introduce **V0.5**:

* Authorization becomes:
  * `signature_valid AND contract_policy_allows(scope, address)`.
* Session-level and task-level grants are stored in an onchain contract.
* Router:
  * Still verifies signatures and derives keys.
  * Queries contract (with caching) for allow/deny decisions.
* Policy updates:
  * Emit events from the contract.
  * Routers subscribe or poll for updates to invalidate caches.

Env allowlist is kept as:

* Emergency override / bootstrap mode.
* Local dev / test environment fallback.

***

### 6. V1 – Ephemeral / Dynamic Node Support

V1 extends private inference to **ephemeral or pooled nodes** (node-pool sessions).

Challenges:

* Miner assignments change over time.
* We can’t rely on static address lists only.

Design points:

1. **Assignment-aware policy**
   * Router confirms that a requesting miner:
     * Is currently assigned to the session/task for this epoch.
     * Has a valid lease or job assignment record.
2. **Replay resistance**
   * Scope string extended for key issuance, for example:
     * `"session:task:epoch:expires_at"`
   * Caller signs this extended scope.
3. **Short-lived grants**
   * Keys for ephemeral sessions/tasks should:
     * Be valid only for short windows (for example, minutes).
     * Align with job assignment lifetimes.

V1 still uses the same keyring, derivation style, and metadata format — the difference is how policy decides who gets keys.

***

### 7. V2 – Unified Key-Issuance Engine

V2 unifies dedicated and ephemeral sessions under a single framework:

* Same auth endpoints:
  * `/api/v1/auth/payload_enc_key/session`
  * `/api/v1/auth/payload_enc_key/task`
* Same signature semantics:
  * Canonical scope strings; explicit `scope_type`.
* Same metadata:
  * `alg`, `scope_type`, `session_id`, `task_id`, `key_version`, `nonce`, `tag`, `ciphertext`, `created_at`.
* Same audit model:
  * Every issuance recorded as an event (who, what scope, which key\_version).

Policy becomes pluggable:

* `EnvAdapter` – env-based allowlist (V0).
* `ContractAclAdapter` – onchain ACL for sessions/tasks (V0.5).
* `AssignmentAdapter` – dynamic assignment info for ephemeral sessions (V1).

Router composes these adapters to compute:

* `authorized = signature_valid AND env_policy_allows(...) AND contract_policy_allows(...) AND assignment_policy_allows(...)`

Encrypted workloads continue to use offchain payload v2 to keep rotation/backfill feasible at scale.

***

### 8. V3 – SDK-Native Private Inference (Web3)

V3 focuses on a Web3 SDK–native experience:

* Web3 client/SDK:
  * Manages wallet-based signing of scope strings.
  * Manages policy registration:
    * Which sessions/tasks require encryption.
    * Which addresses/roles can receive keys.
  * Manages key request + caching flows.
* Router:
  * Remains:
    * Policy enforcement engine.
    * Key issuance service.
  * Does not hold long-lived plaintext DEKs beyond what’s needed to derive them.
* Onchain:
  * Stores transparent policy state and references:
    * Which addresses are allowed.
    * Which sessions/tasks are “private-required”.
  * Never stores raw secrets or seeds.
* 3-party patterns (optional, later):
  * User ↔ Miner ↔ Oracle flow for:
    * Encrypted inference.
    * Verifiable output checking.
  * Converge to envelope encryption:
    * One DEK per session/task.
    * DEK wrapped separately for each authorized recipient.

***

### 9. V4 – TEE-Backed Confidential Inference (Nitro / TDX)

V4 introduces **TEE-backed nodes** as the final, strongest privacy form: even when payloads must be decrypted for model execution, they are only ever decrypted inside a **trusted execution environment** (TEE) such as AWS Nitro Enclaves or Intel TDX.

#### 9.1 Why TEE Nodes Matter

Encrypted payloads + key control protect data in transit and at rest, but at some point, models need plaintext inside RAM to run.

V4 aims to guarantee that:

* Decryption and inference happen only inside a TEE with:
  * Hardware-backed isolation from the host OS/hypervisor.
  * Attestation that proves code + configuration to the router and/or caller.
* Node operators (and cloud providers) cannot inspect plaintext payloads, only resource usage.

This becomes the “final privacy form” for high-sensitivity workloads.

#### 9.2 Initial Target: AWS Nitro Enclaves

Past experience:

* We’ve used **AWS Nitro** and **Intel TDX** for user data privacy projects.
* Nitro is a practical first target because:
  * Once you have a Docker image, it is “one command away” to build a Nitro image.
  * It is straightforward to run a TEE-enabled container on AWS as an enclave.

Initial V4 rollout plan:

* Start with Nitro-enabled miners:
  * Build enclave-compatible images from existing miner containers.
  * Expose a TEE runtime that can:
    * Receive encrypted payloads.
    * Obtain DEKs or wrapped keys only after successful attestation.
    * Run inference locally inside the enclave.
* Later, extend to Intel TDX and other TEE platforms where available.

#### 9.3 Key & Attestation Flow (High-Level)

A typical V4 flow (simplified):

1. Miner node boots a TEE (Nitro/TDX) with a known enclave image.
2. Enclave generates an attestation document describing:
   * Code hash / image hash.
   * Configuration (e.g., models, routes).
3. Router (or a separate attestation service) verifies the attestation:
   * Ensures the enclave matches an allowlisted image/config.
4. For an encrypted job:
   * Router derives or unwraps a DEK for the scope (session/task) as in V2/V3.
   * Router encrypts the DEK to the enclave’s public key (or uses TEE-specific key exchange).
   * Encrypted payload + wrapped DEK are delivered to the enclave.
5. Inside the enclave:
   * Enclave unwraps DEK.
   * Decrypts payload.
   * Runs inference using local models.
   * Optionally re-encrypts results to the user’s key or to a new DEK.
6. Router sees only:
   * TEE attestation claims.
   * Encrypted payloads and results.
   * Metering and success/failure status.

TEE nodes still integrate with:

* Existing keyring versions (`key_version`).
* Offchain payload v2 metadata (same envelope).
* Policy adapters (e.g., only certain sessions/tasks may require TEE execution).

#### 9.4 How V4 Fits the Roadmap

V4 builds on previous versions:

* V0–V2:
  * Define scoped keys, rotation, and metadata.
* V3:
  * Adds Web3 SDK and clean policy registration.
* V4:
  * Uses those same scoped DEKs and policies.
  * Adds a TEE “execution shape” for miners:
    * Some sessions/tasks marked as `privacy_mode = "TEE_REQUIRED"` or similar.
    * Router routes those only to TEE-capable miners.

Over time:

* Nitro-based TEE miners can be the first production path.
* Intel TDX support can be added for on-prem or other cloud vendors.
* Full design doc will extend this section with:
  * Attestation formats.
  * Routing policies.
  * Combined “TEE + encrypted payload” patterns.

***

### 10. Long-Term Rotation & Backfill at Scale

TEE-backed private inference doesn’t remove the need for **operational key hygiene**. Over the long run, Cortensor needs a rotation/backfill story that works at network scale, especially if a seed or key material is suspected to be compromised.

Key considerations:

* **Backfill jobs must preserve offchain URNs/IDs**
  * For most apps, URNs or IDs pointing at offchain payloads (S3 objects, IPFS CIDs behind a pinning layer, etc.) should remain stable.
  * Backfill workers should:
    * Fetch existing ciphertext by URN.
    * Decrypt using the legacy `key_version`.
    * Re-encrypt with the active version.
    * Write back to the same URN / storage key so upstream references do not break.
* **Priority tiers for backfill**
  * Not all encrypted data is equal:
    * “Hot” session/task payloads that agents still need.
    * “Warm” history needed for audits/repairs.
    * “Cold” archives that can be invalidated with lower user impact.
  * Backfill runners should support:
    * Priority queues by namespace / project / app.
    * Configurable SLOs (for example: 95% of hot data re-encrypted within 24h).
* **Compromised-key scenarios**
  * If a seed or specific `key_version` is suspected compromised:
    * Immediately mark that version as “compromised, decrypt-only”.
    * Block new issuance for that version (only decrypt for backfill).
    * Kick off backfill against payloads tagged with that `key_version`.
    * Offer app-level knobs:
      * “Hard invalidate” (refuse to decrypt) for the most sensitive flows.
      * “Best-effort backfill” for less critical archives.
* **Shard-aware backfill**
  * In a multi-router or multi-region world, backfill should be sharded:
    * Each router (or worker pool) handles a subset of URNs or key ranges.
    * Progress tracked via a central index (for example, “encrypted payload index” keyed by `key_version`).
    * Operators can see:
      * How many payloads per key\_version remain.
      * Estimated time to completion.
* **TEE + rotation interplay**
  * When TEE nodes are in use:
    * Backfill workers can optionally run **inside TEEs** as well, so decrypt/re-encrypt never leaves an enclave.
    * A hybrid approach is also possible:
      * Use a privileged “maintenance enclave” with separate attestation + rate limits for rotation jobs.
  * Over time, high-sensitivity tenants may require:
    * “All decrypt/re-encrypt operations must happen within TEE nodes only.”

The main takeaway:

* Keys **will** rotate.
* Some keys **may** become compromised.
* The design assumes:
  * Offchain payload v2 is always re-encryptable in place.
  * URNs/IDs stay stable while the ciphertext behind them gets upgraded.
  * Rotation/backfill is a first-class, observable process — not an afterthought.

***

### 11. Concrete V0 Improvements (Next Work Items)

To harden V0 and prepare for V0.5/V1/V2/V3/V4:

1. Add `key_version` to responses:
   * `/auth/payload_enc_key/session`
   * `/auth/payload_enc_key/task`
2. Require clients to persist `key_version` in encrypted payload metadata.
3. Introduce router keyring env format:
   * `ENCRYPTION_SEED_ACTIVE` and `ENCRYPTION_SEED_LEGACY_*` (or similar).
4. Implement decrypt flow with key\_version-first resolution:
   * Use `key_version` in metadata.
   * Only fall back to legacy/range mapping during migration.
5. Add backfill worker for offchain v2 ciphertext re-encryption to active version (preserving URNs).
6. Enforce that encrypted sessions/tasks must use offchain payload v2 for prompts/results.

***

### 12. Summary

* **V0** gives dedicated-session private inference: router-managed policy, deterministic per-scope keys, and env-based allowlists.
* **V0.5** moves policy into a contract-backed allowlist, with env as emergency fallback.
* **V1** extends privacy to ephemeral / dynamic node pools, with assignment-aware rules and short-lived grants.
* **V2** unifies everything behind a single key-issuance engine and pluggable policy adapters, using the same metadata and audit model.
* **V3** layers on a Web3 SDK–native experience and envelope encryption, turning private inference into a first-class, programmable feature for onchain + offchain apps.
* **V4** adds TEE-backed confidential inference (AWS Nitro / Intel TDX) so that decryption + execution happen only inside hardware-backed enclaves, giving the strongest privacy guarantees for high-sensitivity workloads.
* Across all versions, **key rotation and backfill** are treated as ongoing operational duties:
  * Encrypted payloads live in offchain payload v2.
  * URNs remain stable while ciphertext is upgraded.
  * Compromised keys can be contained via rotation + re-encryption rather than breaking references or rewriting app-level contracts.

This roadmap is intentionally incremental: start with dedicated sessions and env-based allowlists, then steadily layer in contracts, dynamic node pools, unified engines, SDKs, and finally TEE-backed execution — without breaking the core guarantees users expect from private inference on Cortensor.


# Private / Encrypted Inference v0 Spec

> **Status:** Design for Testnet Phase #3 (v0 only – dedicated sessions).\
> **Scope:** How private / encrypted inference works today on *dedicated-node* sessions, including env config, key issuance, offchain payload v2 format, router tool support, and end-to-end execution flow.

***

### 1. High-Level Summary

v0 private inference is **router-centric** and **session-scoped**, and is only supported on the **v2 completion surface**:

* Applies to:
  * `POST /api/v2/completion` (offchain payload–aware completion endpoint).
  * v1 completion endpoints remain non-encrypted / non-offchain for now.
* Only **dedicated sessions** are supported (a router is wired directly to a specific miner or miner group).
* The **router**:
  * Owns a secret keyring (`ENCRYPTION_SEED` + versions).
  * Issues scoped encryption keys via auth endpoints.
  * Encrypts all prompts/results for private sessions.
  * Stores encrypted blobs in an **offchain payload v2** store (e.g., S3).
  * Stores only **URN references** in the Session / SessionQueue records.
* **Miners**:
  * See offchain payload v2 objects with explicit encryption metadata.
  * Ask the router for the right key if they are allowed.
  * Decrypt, run inference, re-encrypt the result, and push it back offchain.
* **Apps** (router owner / dev):
  * Call `/api/v2/completion` against private sessions.
  * Receive decrypted final results from the router.
  * Do not see keys; encryption/decryption is handled inside the router.

Because entire payloads are encrypted, **streaming is not supported** for encrypted v0 workloads.

***

### 2. Components & Roles

* **Router Node**
  * Hosts:
    * Completion endpoint: `POST /api/v2/completion`.
    * Auth endpoints:
      * `POST /api/v1/auth/payload_enc_key/session`
      * `POST /api/v1/auth/payload_enc_key/task`
  * Owns:
    * Encryption keyring (`ENCRYPTION_SEED` + versioning).
    * `ENCRYPTION_ALLOWED_LIST` policy.
    * Offchain payload v2 integration (e.g., S3 bucket, URN scheme).
    * Tooling to:
      * Generate strong secrets for env.
      * Rotate keys and backfill encrypted payloads.
* **Dedicated Miner Node**
  * Assigned to one or more private sessions.
  * Holds an address (EOA) used to authenticate when requesting keys.
  * Has logic to:
    * Detect encrypted payloads in offchain v2.
    * Call router auth endpoints to get keys.
    * Decrypt, run models, re-encrypt outputs.
* **App / User**
  * Talks to router’s `/api/v2/completion`.
  * Selects which sessions are **private** (dedicated, encrypted).
  * Treats encrypted sessions as non-streaming.

***

### 3. v0 Env Configuration

#### 3.1 Encryption Seed (Keyring Root)

Basic v0 uses a single env seed as the root of a versioned keyring:

* `ENCRYPTION_SEED` – strong, random, secret seed used to derive scoped payload keys.

Example (conceptual):

```
ENCRYPTION_SEED="replace-with-strong-random-seed"
```

Keyring model (high-level):

* Internally, the router should behave as if it has:
  * `active_version = vN`
  * `legacy_versions = [vN-1, vN-2, ...]`
* For v0:
  * Encryption uses `active_version`.
  * Decryption checks `key_version` inside the encrypted payload metadata and selects the right seed/version.
  * This requires the router to **retain old seed material** (decrypt-only) until rotation and backfill are complete.

Key derivation (conceptual):

* Deterministic, scoped, versioned:

  K(scope, key\_version) = HKDF(seed\_for\_version, info = "cts:v0:" + scope)

Current SHA-256 derivation is acceptable for early v0, but HKDF-style derivation is the target.

#### 3.2 Allowed List – v0 Policy

`ENCRYPTION_ALLOWED_LIST` controls **who can request keys** and **for which scopes**.

Supported forms:

* Global address – can access keys for all sessions/tasks:

  ```
  ENCRYPTION_ALLOWED_LIST="0xAAA...AAA"
  ```
* Session-scoped – address allowed for a specific session:

  ```
  ENCRYPTION_ALLOWED_LIST="101:0xBBB...BBB"
  ```
* Task-scoped – address allowed for a specific session + task:

  ```
  ENCRYPTION_ALLOWED_LIST="101-9001:0xCCC...CCC"
  ```
* Combined example – commas inside a scope, semicolons between scopes:

  ```
  ENCRYPTION_ALLOWED_LIST="0xAAA...AAA;101:0xBBB...BBB;101-9001:0xCCC...CCC,0xDDD...DDD"
  ```

Semantics:

* `0xAAA...AAA`\
  → Address can request **any** scoped key (any session/task).
* `101:0xBBB...BBB`\
  → Address can request keys for **session 101** (session-level scope).
* `101-9001:0xCCC...CCC`\
  → Address can request keys for **session 101, task 9001** only.

Env format must have:

* No spaces.
* Addresses as `0x` + 40 hex characters.

***

### 4. v0 Auth Endpoints (Key Issuance)

These endpoints are **internal** to the Router’s private inference design and are called by trusted operators (router owner, miners). They are *not* general public APIs.

#### 4.1 Session-Level Key Issuance

* Endpoint: `POST /api/v1/auth/payload_enc_key/session`

Request body (conceptual):

* `address` – caller EOA.
* `signature` – signature over the canonical scope string.
* `session_id` – integer session ID.

Canonical signed message:

* For session scope:

  ```
  "session_id"
  ```

Example for `session_id = 101`:

* Signed string: `"101"`

Router behavior:

1. Verify `signature` matches `address` over `"101"`.
2. Check `ENCRYPTION_ALLOWED_LIST` to see if `address` is allowed for:
   * Global, or
   * `101`, or
   * Any compatible pattern (depending on policy rules).
3. If authorized, derive `payload_enc_key` from:
   * Current keyring seed and
   * Scope string (`"101"`),
   * Associated `key_version`.
4. Return:
   * `payload_enc_key`
   * `key_version` (e.g., `"v3"`).

#### 4.2 Task-Level Key Issuance

* Endpoint: `POST /api/v1/auth/payload_enc_key/task`

Request body (conceptual):

* `address`
* `signature`
* `session_id`
* `task_id`

Canonical signed message:

* For task scope:

  ```
  "session_id:task_id"
  ```

Example for `session_id = 101`, `task_id = 9001`:

* Signed string: `"101:9001"`

Router behavior is the same as session-level, but scope is the pair `(session_id, task_id)` and may use a different policy branch in `ENCRYPTION_ALLOWED_LIST`.

***

### 5. Offchain Payload v2 Format (Encrypted vs Plain)

#### 5.1 Plain Offchain Payload v2 (Baseline)

For **non-encrypted** workloads, offchain v2 is conceptually:

* A JSON document containing:
  * The prompt / input (in plaintext).
  * Optional helper metadata (timestamps, tags, etc.).

The Session / SessionQueue objects store only a **URN** pointing to this JSON blob in S3 (or another blob store). When a miner resolves the URN, it sees a normal JSON payload with plaintext fields.

#### 5.2 Encrypted Offchain v2 (v0 Private Inference)

For **encrypted** workloads, offchain v2 wraps payloads in an encryption envelope with explicit metadata.

Example envelope (conceptual):

```
{
  "version": "v2",
  "payload_type": "encrypted",
  "data": {
    "alg": "aes-256-gcm",
    "scope_type": "session",      // or "task"
    "session_id": 101,
    "task_id": 9001,
    "key_version": "v3",
    "nonce": "base64-encoded",
    "tag": "base64-encoded",
    "ciphertext": "base64-encoded",
    "created_at": "2026-03-01T12:34:56Z"
  }
}
```

Key points:

* `payload_type = "encrypted"` tells miners:
  * This is not plaintext; do not parse `ciphertext` directly.
* `data.alg` and related fields describe:
  * Encryption algorithm.
  * Scope type (session vs task).
  * Scope identifiers.
  * `key_version` used for derivation.
  * Nonce, tag, ciphertext, and timestamp.
* The `ciphertext` contains the entire original prompt JSON (offchain v2 payload body) encrypted under the scoped key.

For **plain** offchain v2 (non-encrypted), the payload would instead have:

* `payload_type = "plain"` (or omitted).
* A `data` object containing plaintext fields (e.g., `prompt`, `metadata`).

***

### 6. End-to-End Flow (v0 Dedicated Session)

This describes the full flow for **one private completion call** on a dedicated session using `/api/v2/completion`.

#### 6.1 One-Time Setup

1. **Router + Miner Pairing**
   * Operator configures a dedicated session (e.g., `session_id = 101`) and assigns it to a specific miner or miner group.
   * Session is marked as:
     * `private = true`
     * `offchain_v2 = true`
2. **Router Env**
   * Set `ENCRYPTION_SEED` to a strong random value.
   * Configure `ENCRYPTION_ALLOWED_LIST` so that:
     * The miner’s EOA is allowed globally or for session `101`.
     * The router owner/operator address is allowed as needed.
3. **Miner Config**
   * Miner has:
     * A configured EOA used as its identity.
     * Logic to:
       * Detect `payload_type = "encrypted"` in offchain v2.
       * Call `/api/v1/auth/payload_enc_key/*` with signed scope strings.
       * Perform AES-GCM decrypt/encrypt and model execution.

#### 6.2 App → Router: Private Completion Call

1. App calls:

   ```
   POST /api/v2/completion
   ```

   with:

   * `session_id = 101`
   * Prompt body in plaintext.
   * Implicitly or explicitly flagged as a **private session** (based on session config).
2. Router receives plaintext request:
   * Checks session `101` config:
     * Private + encrypted.
     * Offchain v2 enabled.
3. Router obtains a **session-level payload key**:
   * Derives from keyring (`ENCRYPTION_SEED` + active version) and scope `"101"`.
   * Internally equivalent to calling the session-level auth logic.
4. Router encrypts the prompt:
   * Uses `alg = aes-256-gcm`.
   * Generates `nonce`, computes `tag`, and produces `ciphertext`.
   * Wraps everything into an offchain v2 envelope with:
     * `payload_type = "encrypted"`.
     * `scope_type = "session"`.
     * `session_id = 101`.
     * `key_version` = current key version.
5. Router uploads encrypted payload to offchain storage (e.g., S3):
   * Stores object keyed by URN, such as:

     ```
     urn:cts:offchain:v2:payload:...
     ```
6. Router updates Session / SessionQueue:
   * Stores **only the URN** (not the plaintext prompt) in its internal records.
7. Router enqueues work for the dedicated miner:
   * Job contains:
     * URN.
     * Session ID / task metadata.
   * No plaintext leaves the router.

#### 6.3 Miner: Decrypt, Run, Re-Encrypt

1. Miner sees a new job for `session_id = 101` with a URN.
2. Miner resolves URN → fetches the offchain v2 blob:
   * Sees:
     * `version = "v2"`
     * `payload_type = "encrypted"`
     * Encryption metadata inside `data`.
3. Miner decides it needs a scoped key:
   * Scope for session-level:

     ```
     "101"
     ```
4. Miner signs the scope string `"101"` with its EOA to generate `signature`.
5. Miner calls:

   ```
   POST /api/v1/auth/payload_enc_key/session
   ```

   with:

   * `address` (miner EOA).
   * `session_id = 101`.
   * `signature` (over `"101"`).
6. Router verifies:
   * Signature is valid for `address`.
   * `address` is authorized by `ENCRYPTION_ALLOWED_LIST`.
7. Router derives `payload_enc_key` and returns it plus `key_version`.
8. Miner uses:
   * `payload_enc_key`
   * `nonce` and `tag` from offchain v2 envelope\
     to decrypt `ciphertext` and recover the original prompt JSON.
9. Miner runs inference locally:
   * Uses whatever model/config is attached to session `101`.
10. Miner prepares encrypted result envelope:
    * Encrypts the model output JSON using the same scoped key and `key_version`.
    * Produces a new offchain v2 object with:
      * `payload_type = "encrypted"`.
      * Updated `ciphertext`, `nonce`, `tag`, `created_at`.
11. Miner uploads encrypted result to offchain storage:
    * Gets a **result URN** for the encrypted output.
12. Miner reports completion back to the router:
    * Updates Session / job record with the result URN.

#### 6.4 Router → App: Decrypt and Return Result

1. Router sees that the job for session `101` is complete:
   * Reads result URN from Session / SessionQueue.
2. Router resolves URN → fetches encrypted result envelope.
3. Router derives or fetches the scoped key:
   * Uses `session_id = 101`.
   * Reads `key_version` from the envelope.
   * Uses keyring to get the correct seed/version.
4. Router decrypts the result:
   * Recovers the plaintext model output JSON.
5. Router returns plaintext result to the app:
   * `/api/v2/completion` response is a normal completion payload (no encryption envelope).

To the app, this looks like a normal completion; the privacy path between router and miner is invisible.

***

### 7. Streaming & Behavior Differences in v0

Because v0 encrypts **entire payloads**:

* `/api/v2/completion` for private sessions is **non-streaming**:
  * Router buffers full prompt → encrypts → offchain.
  * Router buffers full result → decrypts → returns to caller.
* v1 completion endpoints are unaffected and behave as before (no offchain v2 + encryption).
* Logs / telemetry for private sessions must:
  * Avoid logging plaintext prompts/results.
  * Prefer URNs and high-level metadata.

***

### 8. Quick Reference – v0 Checklist

To run v0 private dedicated sessions safely:

1. **Router**
   * Has `ENCRYPTION_SEED` configured and stored securely.
   * Has `ENCRYPTION_ALLOWED_LIST` configured:
     * Global dev/operator and/or specific miner addresses.
   * Supports:
     * `/api/v2/completion` with offchain v2.
     * `/api/v1/auth/payload_enc_key/session` and `/api/v1/auth/payload_enc_key/task`.
   * Integrates:
     * Offchain payload v2 store (e.g., S3).
     * URN generation and resolution.
2. **Sessions**
   * Are explicitly marked as:
     * Dedicated → bound to specific miner(s).
     * Private → require encryption.
     * Offchain v2 → store payloads in blob store, URNs in DB.
3. **Miners**
   * Have an EOA identity.
   * Implement:
     * URN resolution.
     * Encrypted envelope detection and AES-GCM decrypt/encrypt.
     * Auth calls to key issuance endpoints.
   * Never store plaintext payloads in logs.
4. **Apps**
   * Use `/api/v2/completion` against private sessions.
   * Treat them as non-streaming calls.
   * Handle standard plaintext completion responses.

***

### 9. v0 Tooling for Secrets & Key Rotation

To make v0 operational, the router needs **two main tooling paths**:

1. **Secret generation tooling** (one-time or periodic).
2. **Key rotation + backfill tooling** (ongoing operational safety).

All of this applies specifically to **`/api/v2/completion`** and offchain v2 encrypted workloads.

#### 9.1 Secret Generation Tool (Router Operator Utility)

Goal:

* Easily generate a strong `ENCRYPTION_SEED` and write it into router env/config.

Expected behavior:

* CLI (example shape):

  ```
  router-encryption init-seed \
    --config /etc/cortensor/router.env \
    --seed-bytes 32
  ```
* Responsibilities:
  * Generate cryptographically strong random bytes for `ENCRYPTION_SEED`.
  * Encode as safe ASCII (e.g., hex or base64).
  * Write or update env/config file (or secrets backend).
  * Optionally print:
    * Seed fingerprint (e.g., first 8 bytes of hash) for ops verification.
  * Never log the full seed to stdout in production mode.

Notes:

* Only run on **fresh** environments or during a controlled rotation flow.
* Should verify that:
  * The file permissions for config are appropriate.
  * The router will reload or be restarted after the change.

#### 9.2 Key Rotation & Backfill Tool (Router-Side)

Goal:

* Rotate `ENCRYPTION_SEED` and re-encrypt all **router-owned, dedicated private sessions** without breaking references (URNs stay valid).

Constraints:

* Offchain v2 objects must be re-encrypted **in place** or with new blobs under the **same URN** (or under a new URN plus a pointer update).
* Old keys must remain available in **decrypt-only** mode until migration is complete.

Conceptual flow:

1. **Preparation**
   * Generate a new seed (via the Secret Generation Tool).
   * Add it to the keyring as:
     * `key_version = vN+1` (active).
   * Mark old seeds (`vN`, `vN-1`, etc.) as decrypt-only.
2. **Session Enumeration**
   * Tool scans router storage to find:
     * All sessions configured as:
       * Private = true.
       * Offchain v2 = true.
       * Dedicated node sessions owned by this router.
   * For each such session, tool enumerates:
     * Prompt payload URNs.
     * Result payload URNs (if needed).
3. **Backfill Pass (Re-encrypt)**
   * For each URN:
     * Fetch current offchain v2 envelope.
     * Read `key_version` (old version).
     * Use keyring to get the right old key.
     * Decrypt `ciphertext` into plaintext JSON.
     * Re-encrypt plaintext JSON with **new active key version**.
     * Produce a new envelope with:
       * Same structure.
       * Updated `key_version` = active version.
       * New nonce and tag.
     * Write back:
       * Either:
         * Overwrite existing blob at the same URN, or
         * Write a new blob and update router’s internal references to point to the new URN.
   * Maintain audit logs:
     * URN processed.
     * Old `key_version`.
     * New `key_version`.
     * Success/failure status.
4. **Verification**
   * For a sample of URNs:
     * Run a test decrypt path using the active key version.
     * Confirm that:
       * Decryption succeeds.
       * The payload is structurally valid (basic JSON checks).
   * Optionally:
     * Run a dry-run mode that:
       * Decrypts and re-encrypts in memory only.
       * Does not write changes, just validates key readiness.
5. **Finalize**
   * Once all dedicated private session payloads are re-encrypted:
     * Mark old key versions as:
       * “decrypt-only allowed for grace period” or
       * Fully retired (if no old payloads remain).
   * Remove old seeds from keyring when safe.

CLI sketch (example):

```
router-encryption rotate-keys \
  --config /etc/cortensor/router.env \
  --from-version v3 \
  --to-version v4 \
  --scope dedicated-private \
  --dry-run=false
```

Behavior notes:

* **Scope**:
  * In v0, this tool focuses only on:
    * Dedicated node sessions.
    * Router-owned offchain v2 URNs.
  * Shared pools and ephemeral sessions come later (v1+).
* **Safety**:
  * Never delete old blobs or seeds until:
    * Backfill has completed,
    * Verification passed,
    * A grace window has elapsed.
* **Performance**:
  * Should be resumable:
    * Track progress per URN.
    * Allow stopping and continuing without re-processing successfully migrated payloads.

#### 9.3 Router Behavior During Rotation

While rotation/backfill is in progress:

* Decryption path:
  * Must look at `key_version` inside the encrypted envelope.
  * Select the appropriate seed from keyring.
  * Support:
    * Both old and new versions for the migration period.
* Encryption path (for new calls):
  * Must always use the **active** key version only.

This ensures that:

* New traffic is always protected under the newest key version.
* Legacy data is gradually migrated without downtime.

***

This v0 detail document, plus the separate privacy roadmap (v0 → v3/v4 + TEEs), together define how Cortensor introduces **practical, operational private inference** on dedicated sessions:

* Router and miners share scoped, deterministic keys via auth endpoints.
* Payloads move offchain in encrypted v2 envelopes.
* `/api/v2/completion` becomes the **primary encrypted workload entry**.
* Router tools manage:
  * Strong secret generation.
  * Safe key rotation and backfill over time, without breaking URNs or session history.


# v0.5 – Contract-Backed ACL for Dedicated Private Sessions (Session-Based Only)

> Status: Design aligned with current mock implementation\
> Scope: **Session-based privacy and key access only** (no task-level ACL)

***

### 1. Purpose and Scope

v0.5 introduces an **on-chain ACL layer** for **private, dedicated sessions**, replacing most router env-based ACL logic for these flows.

Key points:

* **Scope = session only**
  * Keys are derived and authorized **per `sessionId`**, not per task.
* **One-way privacy**
  * A session becomes *encrypted/private* the first time a miner is added.
  * It **cannot** be downgraded back to non-encrypted.
* **Router integration change**
  * Router must stop treating `ENCRYPTION_ALLOWED_LIST` as the primary ACL source for dedicated private sessions.
  * Router must read from the **session-level allowlist** in this module, **cache it**, and only fall back to env in explicit legacy/emergency modes.

This doc describes the **actual mock implementation**:

* State:
  * `sessionAllowedMiners`
  * `sessionAllowedMinerList`
  * `sessionAllowedMinerIndex`
  * `sessionEncryptionEnabled`
* Functions:
  * `addSessionAllowedMiner`
  * `removeSessionAllowedMiner`
  * `getAllowedMinersCount`
  * `getAllowedMiners`

Session ownership is still resolved via `SessionData` (not in this module).

***

### 2. On-Chain State (Current Mock Implementation)

#### 2.1 Allowlist Core

State layout:

* `mapping(uint256 => mapping(address => bool)) public sessionAllowedMiners;`\
  Membership mapping (already existed).
* `mapping(uint256 => address[]) private sessionAllowedMinerList;`\
  Backing array to enable enumeration/pagination (new, private).
* `mapping(uint256 => mapping(address => uint256)) private sessionAllowedMinerIndex;`\
  1-based index for O(1) removal via swap-and-pop (new, private).
* `mapping(uint256 => bool) public sessionEncryptionEnabled;`\
  Session-level privacy flag.

Semantics:

* `sessionAllowedMiners[sessionId][miner]`\
  → `true` if `miner` is currently allowlisted for that session.
* `sessionAllowedMinerList[sessionId]`\
  → backing array to enumerate allowlisted miners.
* `sessionAllowedMinerIndex[sessionId][miner]`\
  → 1-based index into `sessionAllowedMinerList[sessionId]`; `0` means “not present”.\
  Used for **O(1)** removal via swap-and-pop.
* `sessionEncryptionEnabled[sessionId]`\
  → privacy flag for that session:
  * `false` (default): session is not private/encrypted.
  * `true`: session is **private/encrypted**, cannot be turned off.

***

### 3. Functions and Behavior

#### 3.1 `addSessionAllowedMiner(sessionId, miner)`

Purpose:

* Add a miner to the allowlist for a session.
* Auto-enable session encryption on first use.

Key behavior:

* **Ownership guard**:
  * Only the **session owner** (from `SessionData`) can call this.
* **Idempotent**:
  * If `sessionAllowedMiners[sessionId][miner]` is already `true`, function is a no-op (beyond the ownership check).
* **When miner is not present**:
  1. Set `sessionAllowedMiners[sessionId][miner] = true`.
  2. Append `miner` to `sessionAllowedMinerList[sessionId]`.
  3. Set `sessionAllowedMinerIndex[sessionId][miner] = newIndex` (1-based).
* **Auto-encryption**:
  * If this is the *first* miner added for the session:
    * Set `sessionEncryptionEnabled[sessionId] = true`.
    * This is **one-way**: there is no function to set it back to `false`.

Complexity:

* Time: **O(1)** for membership check + append.
* Storage: grows with number of allowlisted miners per session.

***

#### 3.2 `removeSessionAllowedMiner(sessionId, miner)`

Purpose:

* Remove a miner from the allowlist in **O(1)** time.

Key behavior:

* **Ownership guard**:
  * Only the **session owner** (from `SessionData`) can call this.
* Removal pattern (swap-and-pop):
  * Look up `idx = sessionAllowedMinerIndex[sessionId][miner]`.
  * If `idx == 0`, miner not present → no-op or revert (implementation choice).
  * Else:
    * Compute `lastIdx = sessionAllowedMinerList[sessionId].length`.
    * If `idx != lastIdx`, swap:
      * `last = sessionAllowedMinerList[sessionId][lastIdx - 1]`.
      * `sessionAllowedMinerList[sessionId][idx - 1] = last`.
      * `sessionAllowedMinerIndex[sessionId][last] = idx`.
    * Pop the last element from `sessionAllowedMinerList[sessionId]`.
    * Set:
      * `sessionAllowedMinerIndex[sessionId][miner] = 0`.
      * `sessionAllowedMiners[sessionId][miner] = false`.

Notes:

* **Does not** change `sessionEncryptionEnabled[sessionId]`:
  * Once encryption is enabled, the session stays private/encrypted even if list becomes empty.

Complexity:

* Time: **O(1)**.

***

#### 3.3 `getAllowedMinersCount(sessionId) → uint256`

Purpose:

* Return the size of the allowlist for a session.

Implementation:

* `return sessionAllowedMinerList[sessionId].length;`

Use:

* Call this first before pagination to ensure `offset < count`.

***

#### 3.4 `getAllowedMiners(sessionId, offset, limit) → address[]`

Purpose:

* Paged enumeration of allowlisted miners.

Constraints:

* `offset < totalCount` must hold, otherwise the call will revert.
* For an empty list (`totalCount == 0`), **any** call will revert:
  * Callers must always check `getAllowedMinersCount(sessionId)` first.

Usage:

1. Get total:
   * `uint256 total = getAllowedMinersCount(sessionId);`
2. Page through:
   * Ensure `offset < total`.
   * Fetch a page of size `limit` starting at `offset`.

Example:

* `offset = 0`, `limit = 50` to fetch first page.
* `offset = 50`, `limit = 50` for second page, etc.

Complexity:

* Time: **O(k)** where `k` = size of returned page (`limit`).

***

### 4. How Router Uses This ACL (v0.5, Session-Only)

#### 4.1 Privacy Flag

When a router handles a request for a given `sessionId`:

* Check:
  * `isPrivate = sessionEncryptionEnabled(sessionId);`
* If `isPrivate == true`:
  * Treat the session as **private/encrypted**.
  * All `/api/v2/completion` traffic for that session must:
    * Use **offchain payload v2** with encryption.
    * Disable streaming.
  * Key issuance must enforce ACL via `sessionAllowedMiners`.
* If `isPrivate == false`:
  * Session is non-private/plain.
  * Router can treat it as a normal (unencrypted) session unless explicitly configured otherwise.

***

#### 4.2 Key Issuance (`/api/v1/auth/payload_enc_key/session`)

For **miners**:

1. Caller sends:
   * `session_id`
   * `address` (or implied from signature)
   * `signature` over canonical scope string.
2. Router constructs scope string, for example:
   * `"session:" + session_id`
3. Router verifies signature (e.g., `verify_addr_str_message(scope_str)`).
4. Router verifies ACL:
   * If `sessionEncryptionEnabled(sessionId) == true`:
     * Check `sessionAllowedMiners(sessionId, minerAddr)` via the **public getter**.
   * Else:
     * For non-private sessions, router may still support legacy env-based logic if needed.
5. If `allowed == true`:
   * Derive scoped key with current `key_version`.
   * Return key + version to miner.

**Important:**\
Router implementation must be updated so that for **private dedicated sessions**:

* **Primary ACL is the contract**, not `ENCRYPTION_ALLOWED_LIST`.
* Env-based ACL is **optional fallback** and should be guarded by an explicit feature flag.

***

#### 4.3 Router Caching Strategy

Even though `sessionAllowedMiners` and `sessionEncryptionEnabled` are cheap to read:

* Routers should **cache** for hot sessions:
  * `sessionEncryptionEnabled(sessionId)`
  * Membership checks for active `(sessionId, minerAddr)` pairs.
* Cache invalidation/update should be driven by:
  * Events (if implemented), or
  * Periodic polling with TTL.

This is especially important when many miners are requesting keys for the same active sessions.

***

### 5. Interaction With v0 Private / Encrypted Inference

v0 private inference is **router-centric** and uses:

* Session-scoped encryption keys derived from an `ENCRYPTION_SEED`/keyring.
* Auth endpoints:
  * `/api/v1/auth/payload_enc_key/session`
* Offchain v2 encrypted payloads with metadata such as:
  * `alg`, `scope_type`, `session_id`, `key_version`, `nonce`, `tag`, `ciphertext`, `created_at`.

v0.5 changes **who is allowed** to get keys:

* Instead of `.env`-only ACL (`ENCRYPTION_ALLOWED_LIST`), dedicated private sessions use:
  * `sessionEncryptionEnabled[sessionId]`
  * `sessionAllowedMiners[sessionId][miner]`

for authorization.

Env-based ACL can still exist for:

* Non-private sessions.
* Emergency overrides.
* Legacy testing environments.

But **for dedicated private sessions**, the on-chain ACL is canonical.

***

### 6. Dashboard / UX Flow

#### 6.1 Enabling a Dedicated Private Session

Typical flow:

1. User creates a session (`SessionData` + router).
2. Dashboard allows user to **configure a dedicated node address**.
3. When user chooses to **enable private mode**:
   * Dashboard calls `addSessionAllowedMiner(sessionId, dedicatedNodeAddr)` on-chain.
4. Effects:
   * `sessionAllowedMiners[sessionId][dedicatedNodeAddr] = true`.
   * `sessionEncryptionEnabled[sessionId] = true` (if first miner).
   * Dedicated node address appears in `sessionAllowedMinerList[sessionId]`.

Dashboard UX:

* Show a **one-way warning**:
  * Enabling privacy is **permanent** for this session.
  * Session will use encrypted offchain v2 payloads and **no streaming**.
  * Only allowlisted miners can obtain keys to decrypt payloads.

#### 6.2 Managing Allowlisted Miners

* Add a miner:
  * `addSessionAllowedMiner(sessionId, minerAddr)` (owner only).
* Remove a miner:
  * `removeSessionAllowedMiner(sessionId, minerAddr)` (owner only).
* Query size:
  * `count = getAllowedMinersCount(sessionId)`.
* Paginate:
  * Use `getAllowedMiners(sessionId, offset, limit)` with `offset < count`.

Notes:

* Removing all miners **does not** revert `sessionEncryptionEnabled[sessionId]` to `false`.
* Dashboard should surface this:
  * “Once privacy is enabled, this session stays private; you can change which miners are allowed, but not turn privacy off.”

***

### 7. Ownership & Guards

* **Only the session owner** (as defined in `SessionData`) can:
  * Add miners via `addSessionAllowedMiner`.
  * Remove miners via `removeSessionAllowedMiner`.

This keeps the ownership model simple:

* One source of truth for *who controls a session* (SessionData owner).
* Session-level ACL tracks *which miners are allowed* to serve its private workloads.

There is **no separate router-owner** in this module; router identity/ownership is enforced via `SessionData`.

***

### 8. Optional Next Improvements

The current mock implementation already covers:

* O(1) add/remove membership.
* Paged enumeration.
* One-way privacy enable flag.

Potential next steps:

1. **Events (recommended)**

   * `SessionEncryptionEnabled(sessionId, by, timestamp)`
   * `SessionMinerAllowedAdded(sessionId, miner, by, timestamp)`
   * `SessionMinerAllowedRemoved(sessionId, miner, by, timestamp)`

   These allow router processes to subscribe and immediately refresh caches instead of polling.
2. **Batch operations**

   * `addSessionAllowedMiners(sessionId, address[] miners)`
   * `removeSessionAllowedMiners(sessionId, address[] miners)`

   Most helpful when sessions need to add/remove many miners at once.
3. **Combined status view**

   * `getSessionPrivacyStatus(sessionId) returns (bool enabled, uint256 allowedCount)`

   Useful for:

   * Dashboards.
   * Router introspection APIs.
   * Scripts that need a quick privacy snapshot.

***

### 9. Summary

* v0.5 defines a **contract-backed, session-based ACL** for private dedicated sessions.
* Core state:
  * `sessionAllowedMiners[sessionId][miner]`
  * `sessionAllowedMinerList[sessionId]`
  * `sessionAllowedMinerIndex[sessionId][miner]`
  * `sessionEncryptionEnabled[sessionId]`
* Core behaviors:
  * `addSessionAllowedMiner` (idempotent, O(1), auto-enables encryption on first use).
  * `removeSessionAllowedMiner` (O(1) swap-and-pop).
  * `getAllowedMinersCount` and `getAllowedMiners` (paged enumeration).
* Router changes:
  * For **private dedicated sessions**, key issuance must use **this contract ACL**.
  * Env-based ACL becomes **legacy/emergency** only for these flows.
  * Router must be updated to **read from the contract, cache results**, and only fall back to env when explicitly configured.
* UX:
  * Privacy is **one-way per session**.
  * Dashboard aligns with contract behavior and enforces that once `sessionEncryptionEnabled` is `true`, it stays `true`.

This keeps v0.5 privacy **simple, session-scoped, and effective**, while still leaving room for future task-level scoping or more advanced privacy policies in later versions.


# Private / Encrypted Inference v1.0 – Ephemeral Private Sessions (Draft Spec)

> Status: Early design draft\
> Scope: Extend private / encrypted inference from **dedicated private sessions** to **ephemeral private sessions**\
> Depends on: stability of v0 / v0.5 dedicated-session privacy flow first

***

### 1. Goal

v1.0 extends Cortensor’s privacy model from:

* **v0 / v0.5**
  * private **dedicated-node sessions**
  * static or semi-static ACL for key access

to:

* **v1.0**
  * private **ephemeral-node sessions**
  * dynamic ACL updates as ephemeral nodes are assigned and released

The core idea is:

> Keep the privacy model conceptually similar to dedicated sessions, but make the ACL lifecycle dynamic enough to follow ephemeral node assignment.

***

### 2. Why v1.0 Is Needed

Dedicated private sessions are comparatively simple:

* the dedicated miner set is known ahead of time
* allowlists can be configured once and reused
* session-scoped encryption works well with static membership

Ephemeral sessions are different:

* nodes are assigned dynamically
* nodes may change during the session lifecycle
* the set of nodes that should be allowed to obtain encryption keys is not fixed up front

So v1.0 needs a privacy model where:

* encryption remains **session-scoped**
* key access remains **ACL-based**
* but the ACL is updated **automatically** as ephemeral nodes enter and leave the session

***

### 3. Design Direction

#### 3.1 Reuse Existing PrivacySettingData

Current direction is to **reuse the existing `PrivacySettingData` module** rather than introduce a separate privacy data path for ephemeral sessions.

Why:

* keeps privacy state in one place
* avoids two parallel systems for dedicated vs ephemeral privacy
* lets routers and dashboards check one module for privacy status and allowed nodes
* reduces mental and implementation complexity

So v1.0 is not a “new privacy store”; it is an **extension of the existing privacy module**.

***

### 4. Core Model

#### 4.1 Dedicated vs Ephemeral Privacy in One Module

`PrivacySettingData` should evolve to support both:

* **dedicated private sessions**
* **ephemeral private sessions**

Conceptually, the module needs to know:

* whether a session is private
* what privacy mode the session uses
* which node addresses are currently allowed to obtain encryption keys for that session

A simple mental model:

* **Dedicated private session**
  * ACL changes rarely
  * nodes are manually configured / explicitly allowlisted
* **Ephemeral private session**
  * ACL changes automatically
  * nodes are inserted when assigned and removed when released

***

### 5. Session-Scoped Privacy Remains the Default

Even for ephemeral sessions, the design should stay **session-scoped**, not task-scoped.

That means:

* encryption keys are still derived from **session scope**
* nodes obtain key access because they are currently assigned to the session
* we do **not** create per-task encryption scopes in v1.0

This keeps the mental model aligned with v0.5:

> “If you are an allowed node for this private session, you can access that session’s scoped key while you are assigned.”

***

### 6. Ephemeral Privacy Lifecycle

#### 6.1 Enabling Privacy

When a user enables privacy on an **ephemeral session**:

1. Session is marked as:
   * private/encrypted
   * ephemeral privacy mode
2. The Session module becomes responsible for keeping ACL membership in sync with actual node assignment
3. Any ephemeral node assigned to that session is added to `PrivacySettingData` so it can request the session encryption key

#### 6.2 Node Assignment

When the Session module assigns an ephemeral node to a private session:

1. Session module performs the normal assignment flow
2. As part of that same flow, it adds the node address into `PrivacySettingData` for that session
3. From that point, the node is allowed to call:
   * session-scoped key issuance endpoint(s)
   * and decrypt session payloads for that private session

#### 6.3 Node Release

When an ephemeral node is released from that session:

1. Session module performs the normal release / cleanup flow
2. As part of that flow, it removes the node address from `PrivacySettingData`
3. From that point, the node should no longer be able to request session encryption keys for that session

This is the main difference from dedicated private sessions:

* dedicated = mostly static ACL
* ephemeral = ACL follows the assignment lifecycle

***

### 7. Session Module Responsibilities

v1.0 requires changes in the **Session module**, not just in the privacy module.

The Session module must add hooks in the places where ephemeral nodes are:

* assigned
* reassigned
* released
* force-removed
* expired / timed out

#### 7.1 Add Hook Points

The Session module should identify and instrument all lifecycle points where a node becomes “currently assigned” to a session.

At those points it should:

* call into `PrivacySettingData`
* add the node address to the session ACL if the session is private and ephemeral

#### 7.2 Remove Hook Points

Likewise, every place where a node is no longer authorized to serve that session should remove it from the ACL.

This includes:

* normal release
* replacement by another node
* timeout expiry
* cleanup after failure
* manual/admin release if supported

#### 7.3 Source of Truth

The Session module remains the **source of truth** for assignment state.

`PrivacySettingData` should not try to infer ephemeral membership by itself.

Instead:

* Session module decides who is assigned
* PrivacySettingData mirrors the allowed key-access set

That separation keeps the design simple:

* Session module = assignment authority
* PrivacySettingData = privacy/key ACL store

***

### 8. PrivacySettingData v1.0 Extension (Conceptual)

The module needs additional state so it can represent both dedicated and ephemeral private sessions.

Conceptually it should track:

* private flag for a session
* privacy mode for a session
  * dedicated
  * ephemeral
* allowed node addresses for that session
* optional metadata to distinguish:
  * manually added dedicated nodes
  * dynamically assigned ephemeral nodes

A simple conceptual structure:

* `sessionPrivacyEnabled[sessionId] -> bool`
* `sessionPrivacyMode[sessionId] -> enum { NONE, DEDICATED, EPHEMERAL }`
* `sessionAllowedMiners[sessionId][node] -> bool`

Optional future distinction:

* `sessionAllowedMinerSource[sessionId][node] -> enum { MANUAL, EPHEMERAL_ASSIGNMENT }`

That distinction is not strictly required for first implementation, but it may help with:

* debugging
* dashboards
* avoiding accidental removal of manually configured entries

***

### 9. Key Issuance Flow in v1.0

The encryption-key access pattern remains conceptually the same as v0.5:

1. Node receives an encrypted session payload
2. Node requests the session key from the router
3. Router verifies:
   * caller signature
   * session scope
   * ACL membership in `PrivacySettingData`
4. If authorized, router returns the session-scoped encryption key

What changes in v1.0 is **how the ACL gets populated**:

* dedicated sessions → mostly manual / owner-managed
* ephemeral sessions → Session module updates it dynamically

So from the router’s point of view, the key issuance path may stay almost the same:

* check session privacy enabled
* check node membership in privacy ACL
* issue session-scoped key if allowed

The complexity is shifted into Session-module lifecycle hooks.

***

### 10. Dashboard / UX Implications

#### 10.1 Private Ephemeral Session Enablement

When users enable privacy on an ephemeral session, the dashboard should clearly communicate:

* this is a private/encrypted ephemeral session
* assigned nodes will be dynamically granted temporary key access
* nodes removed from the session will lose key access

#### 10.2 Comparison to Dedicated Privacy

Dashboard should make the distinction visible:

* **Dedicated private session**
  * fixed / manually managed node ACL
* **Ephemeral private session**
  * dynamic ACL based on live assignment

This helps users understand why the node list can change over time for ephemeral sessions.

#### 10.3 Warnings / Constraints

UI should also warn that:

* privacy for ephemeral sessions may be more operationally complex than dedicated sessions
* dynamic membership means debugging may require viewing assignment history
* encryption still disables raw streaming-style flows if full payload encryption is used

***

### 11. Audit / Observability

Because ephemeral ACL membership is dynamic, observability becomes more important in v1.0.

At minimum, the system should record:

* when privacy was enabled for a session
* which nodes were added to ACL due to assignment
* which nodes were removed due to release
* why a node was removed:
  * normal release
  * timeout
  * failure
  * manual intervention

This can be implemented via:

* events in `PrivacySettingData`
* session events in the Session module
* dashboard history views

Without this, ephemeral privacy will be hard to debug.

***

### 12. Security Model

#### 12.1 Principle

A node should only be able to access a private session key if:

* it is currently assigned to that session, and
* the Session module has inserted it into the ACL

#### 12.2 Removal Matters

The remove path is just as important as the add path.

If removed nodes remain in the ACL too long, then:

* old nodes may continue to request keys after they should no longer serve the session

So v1.0 security depends on:

* correct add hooks
* correct remove hooks
* reliable cleanup on edge cases

#### 12.3 Session-Scoped Simplicity

Not introducing task-based encryption in v1.0 helps reduce security mistakes:

* no per-task ACL churn
* no task-by-task router updates
* less coordination overhead

That is why session scope remains the right design for this phase.

***

### 13. What Is Not in Scope Yet

This is still **rough design work**, not final implementation.

Not in scope yet:

* final storage layout for all new mappings
* exact function signatures
* exact event list
* exact dashboard UI flow
* full test matrix
* task-scoped privacy
* advanced key leasing / expiry policies
* TEE-backed private ephemeral sessions

Those can come after the dedicated-session path is stable and the ephemeral design is refined further.

***

### 14. Current Status

What has been done so far:

* rough design pass over the Session module
* identification of likely hook points where ephemeral nodes need to be:
  * added to privacy ACL
  * removed from privacy ACL
* high-level decision to **reuse `PrivacySettingData`** rather than create a new privacy path

What has **not** happened yet:

* implementation
* testing
* finalized storage / interface spec

So this document should be treated as:

> an early architectural direction for v1.0, not a final implementation contract

***

### 15. Summary

v1.0 extends private / encrypted inference from **dedicated private sessions** to **ephemeral private sessions** by reusing the existing `PrivacySettingData` module and making the **Session module** responsible for dynamic ACL updates.

The key model is:

* privacy stays **session-scoped**
* Session module adds assigned ephemeral nodes into privacy ACL
* Session module removes them again when released
* router continues to issue encryption keys based on session-scoped ACL membership

In one sentence:

> v1.0 keeps the dedicated-session privacy model intact, but makes it dynamic enough for ephemeral node assignment and release, without introducing a separate privacy data path or task-scoped encryption.


# IPFS Integration

Cortensor leverages the **InterPlanetary File System (IPFS)** to enable decentralized, content-addressable storage and distribution of data. This integration supports Cortensor’s core mission to deliver scalable, verifiable, and censorship-resistant AI services without relying on centralized infrastructure.

## Overview

IPFS is a peer-to-peer distributed file system that allows files to be stored and accessed using content hashes rather than traditional URLs. In Cortensor, IPFS plays a crucial role in ensuring integrity, traceability, and decentralization across various stages of the AI inference workflow.

## Key Use Cases

#### 1. Inference Input & Output Storage

When users submit large input files (e.g., datasets, documents, media) or receive output files from inference tasks, Cortensor stores these files on IPFS.

* Ensures tamper-proof and immutable storage.
* Files are retrieved using content hashes, enabling verifiable access.
* Keeps heavy data off-chain while maintaining transparency and accessibility.

#### 2. Synthetic Dataset Generation & Distribution

Cortensor’s synthetic data engine generates datasets used for training and fine-tuning AI models. These are distributed using IPFS to ensure open, reproducible access.

* Datasets are versioned, content-addressed, and publicly auditable.
* Enables decentralized data sharing for AI researchers and developers.
* Reduces reliance on centralized hosting services.

#### 3. Cross-Node Task Data Sharing

In distributed AI inference, miners require access to task-related data such as prompts, configurations, and session metadata. Cortensor uses IPFS to:

* Provide reliable access to shared data across geographically distributed nodes.
* Facilitate coordination between session queue, session module, and miners.
* Eliminate bottlenecks caused by centralized APIs.

#### 4. Oracle Proof & Audit Trail

Cortensor’s oracle and validation modules may reference inference results or proof artifacts stored on IPFS:

* Content hashes are written to the blockchain for lightweight verification.
* Enables decentralized audit trails for AI outputs and session behavior.

## Benefits of Using IPFS

| Feature                   | Benefit                                                                   |
| ------------------------- | ------------------------------------------------------------------------- |
| **Decentralization**      | Eliminates reliance on centralized storage providers.                     |
| **Content Addressing**    | Ensures integrity and immutability of input/output data.                  |
| **Scalability**           | Offloads storage-heavy operations from on-chain systems.                  |
| **Interoperability**      | Easily integrated with Web3 clients, smart contracts, and developer SDKs. |
| **Censorship Resistance** | Promotes open and resilient AI infrastructure.                            |

## Summary

The integration of IPFS within Cortensor reinforces the network’s commitment to openness, trust, and verifiability. Whether serving input/output for inference, sharing synthetic datasets, or providing audit trails for oracle validation, IPFS plays a foundational role in supporting Cortensor's decentralized AI ecosystem.


# Security & Privacy

Cortensor prioritizes security and privacy to ensure that user data and network operations remain protected. This section outlines the key mechanisms and strategies implemented to safeguard the Cortensor network.

## **Overview**

Cortensor employs a multi-faceted approach to security and privacy, incorporating encryption, secure communication protocols, and robust validation processes to protect data and maintain trust within the network.

## **Key Mechanisms**

### **Encrypted Communication**:

* All data transmitted within the network is encrypted to ensure privacy and integrity.
* Router nodes manage encryption and decryption, ensuring secure interactions between clients and miner nodes.

### **Data Storage Security**:

* Uses IPFS for decentralized and secure data storage.
* Ensures that data such as prompts and completions are stored off-chain, reducing exposure to potential on-chain vulnerabilities.

### **Staking and Incentives**:

* Nodes stake tokens to participate, ensuring their commitment to network security.
* Staking reduces the risk of malicious behavior, as nodes have a financial incentive to maintain network integrity.

### **Validation and Verification**:

* Validation nodes verify the accuracy of AI inference results using methods like semantic checks, embedding comparisons, and checksum verifications.
* Multiple nodes participate in the validation process to ensure consensus and reliability.

### **Access Control**:

* Implements permissioned access for certain network operations, with plans to transition to a more decentralized, permissionless setting in the future.
* Ensures that only authorized nodes can perform specific tasks, enhancing overall security.

### **Privacy Measures**:

* User data is handled with strict privacy protocols, ensuring that sensitive information is protected throughout the processing and storage lifecycle.
* Future updates will include additional privacy features, such as enhanced data anonymization and secure multi-party computation.


# Privacy Features: Three-Party Encryption

Cortensor is introducing **privacy-preserving features** to enable secure, verifiable inference without exposing sensitive data. At the core is a **three-party encryption model**, allowing the **User, Miner, and Oracle** to establish a shared symmetric session key.

Goals:

* **Confidentiality** – inputs and outputs remain encrypted end-to-end.
* **Trustlessness** – no single party controls the key.
* **Integrity** – all parties contribute fairly to the key generation process.

Two candidate methods have been designed and prototyped:

* **Method 1:** Combined ECDH with Commitment Sharing
* **Method 2:** Coordinator-Based Key Distribution

The network has not yet finalized which approach will be adopted for **SessionV3**.

***

### Method 1: Combined ECDH with Commitment Sharing

#### Concept

All three parties generate a shared key derived from **pairwise ECDH operations**. To ensure that **all three secrets** (`ab`, `ac`, `bc`) are included, each participant shares a **commitment** to the secret that the others cannot compute.

#### Process

1. Each party computes the two pairwise secrets available to them.
2. Each party publishes a **commitment** to the missing secret so the others can combine it deterministically.
3. All parties hash and expand the combined values into a **symmetric session key**.

#### Benefits

* No single party controls the key.
* Symmetric key is never transmitted in plaintext.
* All three participants equally contribute.

#### Considerations

* Requires an **extra communication round** for commitments.
* More complex implementation compared to Method 2.

***

### Method 2: Coordinator-Based Key Distribution

#### Concept

One party acts as a **coordinator**, generates a random symmetric key, and securely distributes it to the others using ECDH-encrypted channels.

#### Process

1. A coordinator is chosen (User, Miner, or Oracle).
2. The coordinator generates a random symmetric key.
3. The coordinator encrypts and distributes the key to the other two parties over secure channels.
4. All three parties align on the same symmetric session key.

#### Benefits

* Simpler, fewer message rounds.
* Flexible — any party can act as coordinator.
* Well-suited when one party naturally initiates the session.

#### Considerations

* Coordinator temporarily controls key generation.
* Slightly weaker decentralization than Method 1.

***

### Current Status

* Both **Method 1** and **Method 2** are functional prototypes.
* No decision has yet been made on which will be adopted for **SessionV3**.
* Final integration will be handled through the planned **SessionKeystore** to manage public keys and session-level key negotiation.

***

### Next Steps

* Benchmark both methods for:
  * **Performance impact** in live sessions.
  * **Complexity of integration** with Router Node and SDK.
  * **Developer experience** (API usability).
* Select a default method for **SessionV3**, while preserving flexibility to support both.

***

⚠️ **Status:** Prototyped. Pending evaluation and selection for SessionV3.


# Modular Architecture and Smart Contract Interactions

In Cortensor, a decentralized AI inference network, several smart contract modules interact with the binary that runs on community nodes. These modules, similar to microservices in modern software architecture, are designed to scale efficiently and allow upgrades over time. The binary interacts with various smart contracts, coordinating tasks for mining and serving user requests across different blockchain layers. This modular design ensures scalability, upgradability, and adaptability as the network expands and evolves.

## Modular Smart Contracts & Microservices Approach

The architecture follows a modular design pattern, with each module containing its own data and functions. These modules can call functions from other modules, making the system flexible for upgrades and feature additions. This is akin to a microservices architecture, where each service operates independently but communicates with others through well-defined interfaces. This logical separation allows Cortensor to scale as more functionalities are added, such as enterprise-level modules or specialized AI features. Over time, we plan to decouple the data within modules to further enhance modularity and ensure each service operates autonomously.

## Core Smart Contract Modules

### **ACL (Access Control Layer)**

The ACL module functions similarly to an access management system. It controls global network access, acting as the gateway for node registration and verification. In the current alpha phase, this module is used to whitelist nodes that can register and join the network, enabling the controlled onboarding of miners and other nodes. ACL also provides a safety measure by allowing the network to blocklist bad actors or nodes that violate network rules. Future iterations will involve setting up ACLs for each module to enhance security by defining access privileges for different modules.

### **IAM (Identity and Access Management)**

IAM is responsible for managing node registrations and maintaining node profiles within the Cortensor network. Each node—whether it’s a miner, router, client, or oracle—must register through IAM before interacting with other modules. It ensures that all participants have defined roles, creating a structured ecosystem. This module acts as the entry point for nodes into the broader network.

### **Cognitive**

The Cognitive module serves as the core of Cortensor’s Proof of Useful Work (PoUW) system, regulating the mining process. It implements the state machine logic that orchestrates AI inference tasks across nodes. This module tracks mining sessions, controls transitions between states (such as Request, Create, Prepare, Precommit, and Commit), and ensures that the tasks are completed within set time limits. The Cognitive module interacts with the **Oracle node** to monitor session times, selects miners via the IAM module, and tracks miner performance via the NodeStats module.

For more detailed information on the Cognitive module and state machine, refer to these resources:\
[Mining Overview](https://docs.cortensor.network/technical-architecture/mining-overview)\
[PoUW State Machine](https://docs.cortensor.network/technical-architecture/consensus-and-validation/proof-of-useful-work-pouw-state-machine)

### **NodeStats**

NodeStats is the module responsible for collecting and analyzing node behavior and performance. Each time a node completes a task or state transition in the mining process, the NodeStats module records its performance using simple metrics like counters and points. Counters track task entry, while points measure whether tasks are completed successfully. This information helps classify nodes and monitor long-term behavior. Over time, these metrics will help categorize nodes and determine their eligibility to serve user requests, laying the groundwork for the node reputation system.

NodeStats also incorporates a heartbeat function, requiring nodes to ping the network to prove they are active. This data is used to determine which nodes are available for task assignment, making NodeStats an essential part of the network’s monitoring and performance evaluation system.

### **Node Reputation**

Node Reputation is a critical extension of the NodeStats module in Cortensor's architecture. While NodeStats captures snapshots of node performance metrics, Node Reputation builds upon this data to create time-series records, offering a longitudinal view of node activity and reliability. This system evaluates node behavior over time, ensuring that active nodes meeting specific thresholds are transitioned to an "ephemeral" state.

Ephemeral nodes are prioritized for user-driven tasks managed by the Session and SessionQueue modules, enabling efficient and reliable AI task processing. The Cognitive module continuously assesses nodes, even those with ephemeral status, to validate their ongoing performance and capabilities. Initially, Node Reputation uses a static set of tracked states, but future iterations will support dynamic state tracking tailored to evolving network demands.

Node Reputation ensures trustworthy task assignments and network health, making it an integral part of Cortensor's decentralized AI infrastructure.

### **Node Pool**

The Node Pool for Ephemeral State is a dynamic system for selecting high-quality inference nodes that have passed cognitive testing. These nodes are available to serve user tasks from the Session Queue and are temporarily reserved when assigned to a session. Once a task is completed, the node undergoes re-validation before rejoining the pool to ensure consistent quality and performance. This process optimizes resource utilization, maintains inference reliability, and ensures only the best-performing nodes remain active in the network.

### **Session**

The Session module handles user requests and AI task configurations. When a user initiates a session, they configure the task requirements, such as desired accuracy and correctness. The user deposits $COR tokens to cover the costs of the task, and miners are assigned based on these configurations. The session also logs the results of each task, storing relevant data in decentralized storage like IPFS, with only the CID (Content Identifier) stored on-chain. This modular approach allows for flexible storage solutions, providing the potential for enterprise-level privacy and data security features.

### **SessionQueue**

The SessionQueue is the task queue that manages job assignments for user sessions. When a session is created, the router node interacts with both the Session and SessionQueue modules. The SessionQueue assigns tasks to miner nodes based on the session’s configurations. Miner nodes can be randomly selected as ephemeral nodes to serve specific tasks within a session, ensuring that tasks are completed efficiently. Over time, SessionQueue will evolve into a smart job router, capable of assigning tasks to nodes based on their capabilities and the complexity of the task at hand.

### Runtime

The **Runtime** module integrates into the binary running on community nodes, acting as a simple key-value storage. This enables:

* **Dynamic Configuration**: Runtime can store values or addresses that control binary behavior without requiring manual configuration updates.
* **Hot-Swapping**: Modules or parameters can be updated in real-time to address issues or optimize performance.
* **Operational Flexibility**: By decoupling configuration updates from the binary itself, Runtime ensures efficient network operations and adaptability to changing requirements.

**Web2 Context for Runtime**

In Web2 systems, runtime configurations are often updated dynamically to manage application behavior without requiring a complete redeployment. Similarly, Cortensor’s Runtime module provides flexibility and operational resilience, ensuring the network remains responsive to real-world demands.

## Future Modules

As the network grows, additional modules may be introduced to support new functionalities and improve network scalability. This modular approach will allow Cortensor to quickly adapt and expand, introducing features like enterprise-level modules or performance optimizations without affecting the overall network.

## Conclusion

Cortensor’s modular, microservice-inspired design allows for seamless upgrades, efficient scaling, and enhanced security. Each module operates independently but can interact with others through well-defined interfaces, ensuring the network remains adaptable to evolving needs. From controlling network access with ACL to handling AI task distribution with the Cognitive and Session modules, Cortensor’s architecture is designed for long-term growth, security, and scalability.

This modular approach enables Cortensor to meet the demands of various industries while maintaining a decentralized and efficient AI network.


# Session Queue

The **Session Queue Module** in Cortensor is a **state machine-controlled task queue system** designed to handle **user tasks**. It is responsible for managing inference requests from users, assigning ephemeral nodes to execute these tasks, and interacting with miners for AI inference processing.

While the **Cognitive Module** focuses on **network tasks** and regulates **task flows** at the infrastructure level, the **Session Queue** is dedicated to **user-driven tasks**, ensuring a structured and reliable execution pipeline.

***

### **Design & Functionality**

The **Session Queue** acts as a **state machine**, processing AI inference tasks submitted by users through the **Session Module**. Miners interact with the **Session Queue** to consume tasks, perform AI inference, and return results.

#### **Task Flow & State Transitions**

The **Session Queue** follows a structured **state transition model**, ensuring data reliability and task integrity. The key states include:

1. **Queued** → Task is received from the Session Module and added to the queue.
2. **Acked** → Ephemeral nodes acknowledge the task and signal readiness to process.
3. **Precommitted** → Miners generate a hash of their inference results, ensuring integrity before submission.
4. **Committed** → Miners submit actual inference outputs, finalizing the process.
5. **Completed** → The task is marked as successfully processed, and results are returned to the user.

These states ensure **structured task handling**, **prevent race conditions**, and **maintain data integrity** throughout the AI inference workflow.

***

### **Interaction with Other Modules**

The **Session Queue Module** acts as an intermediary between key Cortensor components:

* **Session Module** → Pushes user tasks to the Session Queue.
* **Node Pool & Ephemeral Nodes** → Assigns miners to execute tasks.
* **Router Nodes** → Relay results back to users via REST API or WebSocket.
* **Cognitive Module** → Ensures network-wide coordination but does not directly manage user tasks.

***

### **Comparison: Cognitive Module vs. Session Queue**

| Feature              | Cognitive Module                          | Session Queue Module             |
| -------------------- | ----------------------------------------- | -------------------------------- |
| **Primary Function** | Network-wide task management              | User AI task execution           |
| **Task Type**        | Infrastructure & health-check tasks       | AI inference requests            |
| **State Machine**    | Complex with multiple verification layers | Lighter with fewer states        |
| **Interaction With** | Oracle Nodes, Miners                      | Session, Miners, Ephemeral Nodes |

***

### **Current Design & Future Enhancements**

#### **Current Implementation**

* Handles **real-time AI inference requests**.
* Manages **ephemeral nodes** dynamically for task allocation.
* Implements **structured state transitions** for reliability.

#### **Future Considerations**

* **Task Prioritization**: Enhancing scheduling to prioritize urgent AI requests.
* **Load Optimization**: Smarter balancing across multiple miners for faster processing.
* **Adaptive Session Management**: Allowing **dynamic scaling** of ephemeral nodes based on demand.

***

### **Conclusion**

The **Session Queue Module** is a critical part of Cortensor's decentralized AI framework, ensuring **efficient, structured, and scalable** AI inference task management. By leveraging a **state machine approach**, it guarantees **task integrity**, **secure computation**, and **seamless coordination** with miners and ephemeral nodes.


# Node Pool

The **Node Pool** is a dynamic selection mechanism for nodes that have **passed cognitive tests** and are in an **ephemeral state**, meaning they are ready to serve user tasks. This system ensures **high-quality inference nodes** are efficiently assigned to user sessions while maintaining network reliability.

### **Node Lifecycle in the Ephemeral Pool**

#### **1. Node Qualification**

* Nodes must pass **cognitive testing** to ensure they meet **performance and inference quality standards**.
* Once validated, they enter the **ephemeral state** and are placed into the **Node Pool**, making them available for task assignment.

#### **2. Task Assignment**

* When a **user task** arrives in the **Session Queue**, a **suitable node** from the **Node Pool** is selected.
* Once assigned, the node is **marked as reserved** and temporarily removed from the pool while it processes the session.

#### **3. Node Release & Re-Validation**

* After completing the assigned session, the **node is released from its reserved state**.
* Before it **re-enters the Node Pool**, it must undergo a **cognitive validation check** to ensure it continues to meet quality standards.
* If the validation check fails, the node will not be placed back into the pool and may require further testing or recalibration.

### **Key Benefits**

* **High-Quality Inference** – Only nodes that meet performance standards are assigned to user tasks.
* **Dynamic Resource Management** – Nodes are continuously rotated based on demand and performance.
* **Cognitive Validation** – Ensures the reliability and accuracy of AI inference throughout the network.
* **Efficient Session Handling** – Nodes cycle between task execution and availability for optimized resource utilization.

The **Node Pool for Ephemeral State** ensures that only the best-performing nodes remain available for **user tasks**, providing a **robust and scalable** network infrastructure.&#x20;


# Session Payment

The `SessionPayment` smart contract forms the **financial backbone** of the Cortensor session system. It manages **deposits, payments, and withdrawals** between users (sessions) and service providers (nodes/miners), ensuring a secure and transparent accounting process for AI inference services across the decentralized network.

***

### Purpose

* Allow users to deposit ETH or ERC20 tokens for session-based inference requests.
* Track session ownership and network contribution per session.
* Facilitate and allocate payments to nodes based on actual usage.
* Enable nodes to claim their earned payments securely.

***

### Inheritance

* **`AccessControl`**: Provides role-based permissions for contract functions.
* **`ReentrancyGuard`**: Prevents reentrant calls during fund transfers.

***

### Roles

| Role                    | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `ADMIN_ROLE`            | Full administrative control for emergency actions or token recovery                 |
| `SESSION_CONTRACT_ROLE` | Authorized to call payment-related session functions (usually the Session contract) |

***

### Key Data Structures

* **`Account`**: Tracks session data like ID, owner, payment amount, and timestamps.
* **`sessionBalances`**: ETH/token balance associated with each session.
* **`nodeLastUsedTimestamps`**: Timestamp logs for node activity.
* **`sessions`**: Maps session IDs to owner addresses.
* **`sessionNetworkUsage`**: Records cumulative session payments made to the network.
* **`totalNetworkBalance`**: Tracks available funds for node payments.
* **`nodePendingPayments`**: Accumulated payments owed to nodes before withdrawal.

***

### Core Payment Flow

#### 1. Session Deposits

Users deposit ETH (or tokens) via `depositToSession`. Funds are held in the session’s internal balance.

#### 2. Network Contribution

Session-based tasks pay into the network treasury using `payFromSessionToNetwork`, recording usage via `sessionNetworkUsage`.

#### 3. Node Allocation

Payments are distributed to eligible nodes through `allocateNodePayments`, using tracked usage and performance metrics.

#### 4. Node Withdrawals

Nodes can withdraw earned funds via `withdrawNodePayment` once they’re allocated.

***

### Key Functions

#### Session Management

* `registerSession(sessionId, owner)`: Registers a new session.
* `getSessionBalance(sessionId)`: Returns balance of the session.
* `depositToSession(sessionId)`: Allows ETH deposits to a session.
* `withdrawFromSession(sessionId)`: Allows ETH withdrawal by session owner.

#### Network Treasury

* `payFromSessionToNetwork(sessionId, amount)`: Transfers balance from session to network.
* `getSessionNetworkUsage(sessionId)`: Returns total contribution of a session to the network.

#### Node Payments

* `allocateNodePayments(address[] nodes, uint256 amountPerNode)`: Allocates payments to active nodes.
* `withdrawNodePayment(address node)`: Allows nodes to withdraw their funds.
* `updateNodeLastUsedTimestamp(address node)`: Updates node's last usage.
* `deleteNodeLastUsedTimestamp(address node)`: Removes node usage entry.

#### Admin & Emergency

* `adminWithdrawToken(tokenAddress)`: Allows recovery of mistakenly sent tokens.
* Emergency ETH withdrawal for recovery and debugging.

***

### Security Features

* **Role-Based Access**: Only authorized contracts and admins can perform sensitive actions.
* **ReentrancyGuard**: Protects ETH withdrawal functions.
* **Balance & Session Validations**: Prevent overdrafts or unauthorized access.
* **Per-Session Tracking**: Clear accounting for funds paid into the network.

***

### Events

| Event                                    | Trigger                          |
| ---------------------------------------- | -------------------------------- |
| `DepositToSession(sessionId, amount)`    | When user deposits ETH           |
| `WithdrawFromSession(sessionId, amount)` | When session owner withdraws ETH |
| `SessionRegistered(sessionId, owner)`    | New session registration         |
| `NodeTimestampUpdated(node)`             | Node activity timestamp update   |
| `PaymentToNetwork(sessionId, amount)`    | Session pays into the network    |
| `NodePaymentAllocated(node, amount)`     | Payment allocated to node        |
| `NodePaymentWithdrawn(node, amount)`     | Node claims their earned payment |

***

### Summary

The `SessionPayment` contract plays a **crucial role in managing payments** between users and the network. It ensures:

* Transparent and secure session-level accounting.
* Accurate tracking of network contributions.
* Fair and reliable reward distribution to nodes.
* Protection against common security vulnerabilities.

This module is essential for sustaining Cortensor's decentralized economic model while maintaining operational accountability and trust across participants.


# Development Previews

The following development previews were shared through social media to show various aspects of Cortensor. This page will serve to share more upcoming development previews. Check the links below to see the demo videos:

### Youtube Channel:

<https://www.youtube.com/@Cortensor>

### **Dev Preview #1: PoUW State Machine (Mining)**

[**https://www.canva.com/design/DAGOXaukn68/o8ngN26d\_rj\_pJU3byvKxg/watch**](https://www.canva.com/design/DAGOXaukn68/o8ngN26d_rj_pJU3byvKxg/watch?utm_content=DAGOXaukn68\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=hdb500d8fe7)

[~~**https://x.com/cortensor/status/1825791265499394153**~~](https://x.com/cortensor/status/1825791265499394153)

### **Dev Preview #2: Miner Node & Oracle Node in Action**

[**https://www.canva.com/design/DAGPxiB-FSA/ItFU06SbTbHBGqVzzEPv2A/watch**](https://www.canva.com/design/DAGPxiB-FSA/ItFU06SbTbHBGqVzzEPv2A/watch?utm_content=DAGPxiB-FSA\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=h089a16b4c4)

[~~**https://x.com/cortensor/status/1831622193287192926**~~](https://x.com/cortensor/status/1831622193287192926)

### **Dev Preview #3: User Interaction & Node Communication**

[**https://www.canva.com/design/DAGQcAag-TI/DjSayawK-xtyNMdc1fwIbA/watch**](https://www.canva.com/design/DAGQcAag-TI/DjSayawK-xtyNMdc1fwIbA/watch?utm_content=DAGQcAag-TI\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=h46a1c58e41)

[~~**https://x.com/cortensor/status/1834867254087098642**~~](https://x.com/cortensor/status/1834867254087098642)

### **Dev Preview #4:** Multiple Miners Collaboration with Oracle Node

[**https://www.canva.com/design/DAGU1ZlgYuI/hMIimgToLyrgKsDS158C2Q/watch**](https://www.canva.com/design/DAGU1ZlgYuI/hMIimgToLyrgKsDS158C2Q/watch?utm_content=DAGU1ZlgYuI\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=h2a21c268b9)

[~~https://x.com/cortensor/status/1850816589018673253~~](https://x.com/cortensor/status/1850816589018673253)

### Dev Preview #5: Multiple Miners Serving User AI Requests via Router Node

[**https://www.canva.com/design/DAGWWLAlvyw/XmoVB-8lPz4KGgse9PCUog/watch**](https://www.canva.com/design/DAGWWLAlvyw/XmoVB-8lPz4KGgse9PCUog/watch?utm_content=DAGWWLAlvyw\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=hd056719d1c)

[~~https://x.com/cortensor/status/1856650888640946523~~](https://x.com/cortensor/status/1856650888640946523)

### Dev Preview #6: Web3 SDK Client & AI Task Execution

<https://x.com/cortensor/status/1899442719757570309>\
<https://www.canva.com/design/DAGha4JEl3c/J1Z7FaHjeSVmnHeopkyCpA/watch>

### Dev Preview #7: Web2 Client, Router, & Miner Interaction

<https://x.com/cortensor/status/1900513998451433639>\
<https://www.canva.com/design/DAGhsp2stf0/3PX9deb2UZjqYfImVSWksg/watch>

### Dev Preview #8: Web2 SDK / REST Stream (Per LLM Token)

<https://x.com/cortensor/status/1902533306698363284>\
<https://www.canva.com/design/DAGiWZ4WapE/fuMo5x4j6KykYt0yi8h6QQ/watch>

### Dev Preview #9: Session UI + Web3 Task Flow (Early Demo)

<https://x.com/cortensor/status/1914983548173648275>

<https://www.canva.com/design/DAGlcIJUkEU/wGax2oEki4gQOXkk1tZnHg/watch>

### Dev Preview #11: Web2 RESTful API Streaming + Example Flows (Video Preview)

<https://x.com/cortensor/status/1920109354038026584>\
<https://www.youtube.com/watch?v=jQeElvJSLOI>

### Upcoming Dev Previews:

* ~~Multiple Miners in Action~~
* ~~Multiple Miners Serving User Requests~~
* ~~Mining Dashboard~~

Stay tuned for more updates as we continue to release additional previews and demos!

***

## Alpha and Closed/Early Testing Signup

Cortensor is preparing for its alpha and early testing phases, and we invite interested participants to sign up for these exclusive opportunities. Early testers will have access to experimental features, contribute to the network’s development, and help us fine-tune our platform before the broader release.

To sign up for closed alpha or early testing, please fill out the **Alpha Testing Signup Form** here:\
\
<https://forms.gle/22hBafYmCFetRjcn7><br>

*Note: This form is in its early stages and may change over time as we refine our processes. Stay informed for any updates!*


# Multiple Miners Collaboration with Oracle Node

This new **Dev Preview** builds upon our **Cortensor Miner & Oracle Nodes Collaboration**. Now, we’re demonstrating **oracle nodes** with **multiple miners** working together in action! Get ready to see **7 miners** operating from diverse data centers across US-EAST, US-WEST, US-Central, and the UK 🌎 – showing that Cortensor runs seamlessly across a variety of hardware configurations. 🔥\
\
[**Multi-Miner Collaboration with Oracle Nodes Video**](https://www.canva.com/design/DAGU1ZlgYuI/hMIimgToLyrgKsDS158C2Q/watch?utm_content=DAGU1ZlgYuI\&utm_campaign=designshare\&utm_medium=link\&utm_source=editor)

### Node Setup Overview

Each miner is assigned via our **ACL** and **IAM modules** on Arbitrum Sepolia to validate nodes and control permissions:

* **ACL Module**: <https://sepolia.arbiscan.io/address/0xca453065e8b8a02364543fe62b68d5ff23a62547>
* **IAM Module**: <https://sepolia.arbiscan.io/address/0x76a5d15610010907cbf624fdb372ebafbe7f01fd>

### About the Preview Video 🎬

The 12:30-minute video features **8 nodes** (1 oracle and 7 miners) on-screen with:

* Top-left: **Oracle node**
* Remaining nodes: Labeled Miner nodes #1-7

💻 Each node runs the **same cortensord binary**, verified using `file` & `ls` commands to ensure consistency across configurations.

### Quantization for Broad Hardware Support

Miners in this demo range from VPS to dedicated Intel E3/E5 servers, utilizing **4-bit quantized LLaVA/LLaMA2** models (about 4GB). This allows efficient mining on modern devices. More on our quantization approach here:

* **Quantization Info**: <https://docs.cortensor.network/technical-architecture/ai-inference/quantization>

### Model Details

* **Model Type**: LLaVA, fine-tuned on GPT-generated multimodal data. An open-source transformer-based chatbot capable of auto-regressive language generation.

### Video Walkthrough Highlights

1. **50s**: After setup, nodes initiate the model download via **IPFS**, starting to signal readiness by pinging the **NodeStats** contract.
2. **2:20**: **Miner #5** begins mining and interacting with the **Cognitive Module contract** – the core of our PoUW state machine and mining process.
   * **Cognitive Module**: <https://sepolia.arbiscan.io/address/0xf4ef23c1c1969d24cafaaa489c4e3a27cd203549>
   * **NodeStats Module**: <https://sepolia.arbiscan.io/address/0xeeb24040108f5fded67612e6cb24f7f4e5d0ed90>

Throughout the video, we highlight each mining node in action, with certain nodes competing or working in parallel, giving insights into real-time mining dynamics.\
\
More on our modular architecture and smart contract interactions:\
[https://docs.cortensor.network/technical-architecture/modular-architecture-and-smart-contract-interactions](/technical-architecture/modular-architecture-and-smart-contract-interactions)

### Deep Dive into Contract Operations

Around **10:15**, we open an Arbitrum Sepolia browser and explore contract operations on **Arbiscan**:

* **Cognitive, NodeStats, IAM, and ACL** contracts.

This segment allows you to see live transaction data, inference input, and output directly linked to mining actions. Feel free to explore these Sepolia contracts for further details on each transaction's data set and mechanics!


# Web3 SDK Client & Session/Session Queue Interaction

This development preview video (**2:30 min**) demonstrates the interaction between **distributed miners** and the **Cortensor Web3 SDK client**. It highlights how the **Session & Session Queue modules** handle user input and distribute AI inference tasks across the decentralized network.

{% embed url="<https://www.canva.com/design/DAGha4JEl3c/J1Z7FaHjeSVmnHeopkyCpA/watch>" %}

### **Key Modules Demonstrated**

* **Web3 SDK Client** – The interface through which users interact with Cortensor’s AI inference system.
* **Session & Session Queue Modules** – Responsible for handling and assigning user input to network miners.
* **Cognitive Module** – Ensures network health, SLA enforcement, and node classification.

### **Demonstration Flow**

1. The user submits inference tasks via the **Web3 SDK Client**.
2. The **Session & Session Queue Modules** dynamically route tasks across the network.
3. Miners process tasks based on availability and hardware capabilities.
4. The system collects and returns results from the miners to the user.

### **What’s Shown in the Video?**

The preview features **three core components** of the Cortensor network:

* **Contabo VPS2 US West** – A miner running on an **AMD CPU**.
* **Vultr A16 Nvidia Instance** – A miner utilizing **GPU inference**.
* **Contabo VPS2 US Central** – A **client instance** running the Web3 SDK, sending inference requests to the network.

### **Development Status**

#### **Early-Stage Implementation**

* Current implementation is still in **early development**, with **latency optimizations underway**.
* The speed will **improve** as we transition to the **v1 codebase**.

#### **Upcoming Integrations**

* **Web2 real-time response** via **WebSocket & REST Stream API**.
* **Router Node & Node Pool support** for improved **scalability & efficiency**.
* **Full v0 to v1 codebase migration** to enhance **performance & reliability**.

### **Future Improvements**

* **Reduced inference latency** for faster response times.
* **Real-time streaming capabilities** for more seamless interactions.
* **Optimized network routing** for improved **task distribution & miner selection**.

### **Reference: Previous Development Preview**

The following **v0 development previews** demonstrate the evolution of Cortensor’s inference request handling. These earlier versions serve as a **blueprint** for the **current v1 development**.

1️⃣ **Single Miner Interacting with Router via Web2/Web3 SDK Client**

* A single miner interacting with the router to serve user requests.
* **Watch here:** <https://www.youtube.com/watch?v=QWaL6rc0cv0>

2️⃣ **Multiple Miners Serving User Inference Requests**

* Showcases miners, the router, and Web3/Web2 SDK clients in action.
* **Watch here:** <https://www.youtube.com/watch?v=2l90bBe0lXA>

As we **migrate from v0 to v1**, these foundational concepts are being **expanded, refined, and optimized** to support a **scalable, decentralized AI inference network**.&#x20;


# Technical Threads

This page serves as a central resource for Cortensor's technical threads on X (formerly Twitter), offering simplified explanations and insights into various components of the network. Each thread provides accessible overviews of Cortensor’s core technology.

### Understanding Cortensor’s Multi-Layered AI Network

Cortensor is structured into three key layers—L1, L2, and L3—each playing a distinct role in ensuring secure and seamless network operations.

* <https://x.com/cortensor/status/1888345710938181811>
* <https://medium.com/@cortensor/understanding-cortensors-multi-layered-ai-network-0ebf7aa67614>

### Understanding Mining in Cortensor: A Deep Dive <a href="#id-8c53" id="id-8c53"></a>

This thread provides an accessible overview of Cortensor's mining mechanisms, explaining how they contribute to network health and quality.

* <https://x.com/cortensor/status/1891761671552762007>
* <https://cortensor.medium.com/tech-understanding-mining-in-cortensor-a-deep-dive-51626cadee60>

### **User Interaction & Node Communication in Cortensor**

Learn about how user interaction and node communication are organized in Cortensor, facilitating efficient task distribution and AI inference across the network.

* <https://x.com/cortensor/status/1894294533757964706>
* <https://cortensor.medium.com/from-request-to-result-how-users-nodes-interact-in-cortensor-b39939b48fe1>

### **Understanding Cortensor's Core Modules & Loading Sequence**

An in-depth look at the essential modules within Cortensor, covering their functions, inter-module communication, and the loading sequence that ensures smooth operations.

* <https://x.com/cortensor/status/1902533306698363284>
* <https://cortensor.medium.com/understanding-cortensors-core-modules-node-initialization-a12fc50cb253>

### ~~How Cortensor Empowers Decentralized AI Agents & Inference in Crypto~~

* [~~https://x.com/cortensor/status/1857013874760790151~~](https://x.com/cortensor/status/1857013874760790151)

### How Cortensor Ensures Decentralized Trust with PoI, PoUW, and Validators

* <https://x.com/cortensor/status/1914915485206110651>
* <https://cortensor.medium.com/how-cortensor-ensures-decentralized-trust-with-poi-pouw-and-validators-535aa743dbc4>

### Endless User Cases for Decentralized AI

* <https://x.com/cortensor/status/1918787019645636749>
* <https://cortensor.medium.com/cortensor-expanding-use-cases-for-decentralized-ai-b79d929c3e36>

### How Cortensor Redefines Decentralized AI and Outpaces the Competition

* [h~~ttps://x.com/cortensor/status/1867132258295173627~~](https://x.com/cortensor/status/1867132258295173627)

### Empowering AI Agents with PoI for Smarter Decisions

* [h~~ttps://x.com/cortensor/status/1873669483975544986~~](https://x.com/cortensor/status/1873669483975544986)

***

## Short/Overview Threads

### Layered Architecture: Optimizing Security, Scalability & Privacy <a href="#c540" id="c540"></a>

* <https://x.com/cortensor/status/1896072576822288719>
* <https://cortensor.medium.com/cortensors-layered-architecture-optimizing-security-scalability-privacy-13b49b83ac4c>

### Optimized Mining Process: Redefining Decentralized AI Execution

* <https://x.com/cortensor/status/1898321740910191101>
* <https://medium.com/@cortensor/optimized-mining-process-redefining-decentralized-ai-execution-45736661ec3e>

### Simplifying Cortensor’s Core Modules & Node Loading Sequence <a href="#abbc" id="abbc"></a>

* <https://x.com/cortensor/status/1904267506325553483>
* <https://cortensor.medium.com/simplifying-cortensors-core-modules-node-loading-sequence-b269d1e3b97d>

### How Cortensor Use Cases Transform AI Across Industries <a href="#id-3d47" id="id-3d47"></a>

* <https://x.com/cortensor/status/1920387978737955101>
* <https://cortensor.medium.com/how-cortensor-use-cases-transform-ai-across-industries-09ade3714214>

Stay tuned for these insights as we continue to break down Cortensor’s innovative framework!<br>


# AI Agents and Cortensor's Decentralized AI Inference

AI agents are autonomous software entities designed to perform tasks and make decisions based on various inputs. They are increasingly vital across numerous industries, handling functions like customer service, data analysis, and process automation. However, traditional AI agents often rely on centralized infrastructure, which can limit scalability, increase costs, and raise concerns about privacy and resilience.

Cortensor's decentralized AI inference network offers a transformative approach by utilizing a community-driven model that enhances the capabilities of AI agents. This decentralized architecture not only addresses the limitations of traditional systems but also provides a robust framework for deploying AI services efficiently.

## How Cortensor's Decentralized Inference Enhances AI Agents

### **Scalability and Cost Efficiency**

Cortensor's network of distributed miners provides the necessary computational power for scaling AI inference tasks. This decentralized structure allows for cost-effective scaling as demand increases, enabling AI agents to handle a high volume of inferences without incurring the high operational costs associated with centralized platforms.

### **Enhanced Reliability and Availability**

Operating across a decentralized network minimizes the risk of downtime associated with single points of failure. This architecture ensures that AI agents remain operational even if some nodes experience issues, making it particularly valuable for mission-critical applications where reliability is paramount.

### **Privacy and Data Security**

Cortensor supports both Web2 and Web3 integrations, allowing AI agents to interact securely with its infrastructure through smart contracts and decentralized storage solutions like IPFS. This approach enhances data privacy by ensuring that sensitive information is managed in compliance with privacy regulations, which is crucial for sectors such as finance and healthcare.

### **Advanced Task Validation and Quality Assurance**

Cortensor employs Proof of Inference (PoI) and Proof of Useful Work (PoUW) mechanisms to ensure the accuracy and relevance of tasks performed by AI agents. PoI verifies that tasks are executed correctly using appropriate models, while PoUW guarantees that tasks contribute meaningfully to the overall system. This validation process enhances the reliability of outputs from AI agents.

### **Adaptive Resource Allocation through Smart Modules**

The modular design of Cortensor's network allows for dynamic task allocation based on real-time availability and requirements. Smart contract modules like SessionQueue manage resource needs efficiently, ensuring optimal performance for AI agents while reducing latency.

## Key Use Cases for AI Agents on Cortensor

* **Customer Service Automation**: With Cortensor's decentralized inference, AI agents can efficiently manage large volumes of customer interactions, scaling rapidly without server overload risks.
* **Autonomous Decision-Making**: In sectors requiring quick decisions based on extensive data sets—such as finance or healthcare—Cortensor enables timely and accurate inferences.
* **AI-Powered dApps**: Decentralized applications can harness Cortensor-powered AI agents to provide enhanced services like real-time analytics and personalized recommendations while maintaining decentralized integrity.

## The Future of Decentralized AI Agents

Cortensor’s decentralized inference framework is pivotal for the future deployment of AI agents. By eliminating reliance on centralized systems, it empowers developers and businesses to create resilient, scalable, and secure AI solutions. This shift not only democratizes access to advanced AI capabilities but also aligns with broader trends in decentralization within the tech ecosystem.

As the landscape evolves, initiatives like Coinbase's "Based Agent" creator illustrate the growing integration of AI with blockchain technology. This tool allows developers to create personalized crypto agents quickly, enhancing the interaction between artificial intelligence and cryptocurrency\[4]. Additionally, discussions around the rise of memecoins highlight how cultural phenomena can be leveraged by AI bots to drive engagement in digital economies\[3]. The combination of Web3 principles with advanced AI capabilities is expected to drive innovation across multiple sectors, enhancing user experiences while ensuring security and privacy\[2].

In conclusion, Cortensor’s decentralized architecture represents a significant advancement in the deployment of AI agents, setting a foundation for future innovations that prioritize scalability, reliability, and user trust in an increasingly digital world. As these technologies evolve, they promise to reshape interactions across various industries while fostering a more equitable distribution of information and resources in the digital landscape.

Citations: \
\[1] <https://www.microsoft.com/en-us/worklab/work-trend-index/copilots-earliest-users-teach-us-about-generative-ai-at-work> \
\[2] <https://blog.spheron.network/a-guide-to-ai-agents-what-you-need-to-know> \
\[3] <https://a16zcrypto.com/posts/podcast/> \
\[4] <https://finance.yahoo.com/news/coinbase-unveils-fast-ai-agent-083703671.html>


# Infographic Archive

This page serves as a comprehensive archive for all Cortensor infographics, designed to provide quick overviews of specific components or single topics from our technical and overview threads. These infographics are concise, visual explanations posted on X (formerly Twitter), aimed at simplifying complex concepts for easy understanding and engagement.

Infographics are ideal for users seeking a snapshot of Cortensor’s innovative architecture, mechanisms, and use cases. They complement our detailed technical documentation by offering bite-sized insights into various aspects of our decentralized AI network. Whether you're exploring mining processes, validation mechanisms, or blockchain architecture, these infographics offer a fast and engaging way to understand key elements of Cortensor.

Below is the complete list of our infographics with their titles and links to the original X posts for further exploration.

### Infographic #1: Mining Process - PoUW State Machine

* <https://x.com/cortensor/status/1886986480494723322>
* <https://cortensor.medium.com/infographic-1-mining-process-state-machine-2fd29da3b62d>

### Infographic #2: Task Submission & Processing

* <https://x.com/cortensor/status/1887398793047646657>
* <https://cortensor.medium.com/infographic-2-task-submission-processing-e4cf43ce98b3>

### Infographic #3: PoUW State Machine - Summary of Each State

* <https://x.com/cortensor/status/1887684063177416977>
* <https://cortensor.medium.com/infographic-3-pouw-state-machine-227e2afdc33f>

### Infographic #4: Router Node Communication Flow

* <https://x.com/cortensor/status/1887951228770074770>
* <https://cortensor.medium.com/infographic-4-router-node-communication-flow-7fbb1644bf50>

### Infographic #5: Core Modules Overview

* <https://x.com/cortensor/status/1888699955734528164>
* <https://cortensor.medium.com/infographic-5-core-modules-the-backbone-of-cortensor-0863f819d972>

### Infographic #6: Node Startup Sequence

* <https://x.com/cortensor/status/1889104022847857110>
* <https://cortensor.medium.com/infographic-6-node-startup-sequence-67d2e0e63e4e>

### Infographic #7: Dynamic Clustering for Tasks

* <https://x.com/cortensor/status/1889460584703484080>
* <https://cortensor.medium.com/infographic-7-dynamic-clustering-for-task-prioritization-cf8ab31551d2>

### Infographic #8: Trust vs Trustless Inference

* <https://x.com/cortensor/status/1889797099572834591>
* <https://cortensor.medium.com/infographic-8-trust-vs-trustless-ai-inference-92285a934ddf>

### Infographic #9: Consensus - Proof of Inference (PoI)

* <https://x.com/cortensor/status/1890173840690692227>
* <https://cortensor.medium.com/infographic-9-consensus-proof-of-inference-poi-afbc76bc225e>

### Infographic #10: Consensus - Proof of Useful Work (PoUW) Framework

* <https://x.com/cortensor/status/1890533432654278938>
* <https://cortensor.medium.com/infographic-10-consensus-proof-of-useful-work-pouw-framework-582dc8c66c6e>

### Infographic #11: Node Stats & Reputation - Accumulation & User Tasks

* <https://x.com/cortensor/status/1890891541847376278>
* <https://cortensor.medium.com/infographic-11-node-reputation-point-accumulation-user-tasks-dcc237a8538a>

### Infographic #12: User Task Process - User to Miner Flow

* <https://x.com/cortensor/status/1891250616338690129>
* <https://cortensor.medium.com/infographic-12-user-task-process-from-request-to-execution-dc9e0c5b5c08>

### Infographic #13: User Session - Session Creation

* <https://x.com/cortensor/status/1891562723928105140>
* <https://cortensor.medium.com/infographic-13-session-module-user-session-creation-73cffb76c33b>

### Infographic #14: Validation Mechanisms

* <https://x.com/cortensor/status/1892125772984484352>
* <https://cortensor.medium.com/infographic-14-validation-mechanisms-b9fa3d061e70>

### Infographic #15: Layer Architecture

* <https://x.com/cortensor/status/1892675967291994314>
* <https://cortensor.medium.com/infographic-15-layered-architecture-security-efficiency-privacy-efb9399757b9>

### Infographic #16: Mining Process - Key Components

* <https://x.com/cortensor/status/1893041849650290976>
* <https://cortensor.medium.com/infographic-16-mining-process-key-components-5ad3af88585a>

### Infographic #17: Parallel Processing Across Miners

* <https://x.com/cortensor/status/1893396809479004290>
* <https://cortensor.medium.com/infographic-17-parallel-processing-across-miners-03d923a409bb>

### Infographic #18: Multi-layered Blockchain Architecture - L1, L2 & L3

* <https://x.com/cortensor/status/1893766515675254856>
* <https://cortensor.medium.com/infographic-18-multi-layered-blockchain-architecture-l1-l2-l3-b70f80c790b8>

### Infographic #19: Proof of Inference - Embedding Vector Distance

* <https://x.com/cortensor/status/1894129142238720214>
* <https://cortensor.medium.com/infographic-19-proof-of-inference-embedding-vector-distance-f205b0f0ade6>

### Infographic #20: AI Models - Centralized vs Decentralized

* <https://x.com/cortensor/status/1894529758610035109>
* <https://cortensor.medium.com/infographic-20-ai-models-centralized-vs-decentralized-eff8783d75e2>

### Infographic #21: Mining Progress - User Control & Miner Collaboration

* <https://x.com/cortensor/status/1894848971027423669>
* <https://cortensor.medium.com/infographic-21-mining-process-user-control-miner-collaboration-42aa744fa951>

### Infographic #22: Proof of Useful Work (PoUW) - Task Levels

* <https://x.com/cortensor/status/1895213176373027316>
* <https://cortensor.medium.com/infographic-22-proof-of-useful-work-pouw-task-levels-97c3e0ef1baa>

### Infographic #23: AI Approach - Centralized vs Decentralized

* <https://x.com/cortensor/status/1895570207680446564>
* <https://cortensor.medium.com/infographic-23-ai-approach-centralized-vs-decentralized-d6348ff80f9d>

### Infographic #24: Proof of Useful Work (PoUW) Overview

* <https://x.com/cortensor/status/1895939413949260110>
* <https://cortensor.medium.com/infographic-24-proof-of-useful-work-pouw-workflow-0187cc32fb16>

### Infographic #25: Cortensor Network Framework

* <https://x.com/cortensor/status/1896647047530618915>
* <https://cortensor.medium.com/infographic-25-cortensor-network-framework-943e22e8c432>

### Infographic #26: ACL Benefits

* <https://x.com/cortensor/status/1897022849996742778>
* <https://cortensor.medium.com/infographic-26-acl-the-security-backbone-95bc2fbd1c6c>

### Infographic #27: Reshaping Decentralized AI

* <https://x.com/cortensor/status/1897383703321747832>
* <https://cortensor.medium.com/infographic-27-reshaping-decentralized-ai-eeb969223dd6>

### Infographic #28: Validation Process - Rewards & Penalties

* <https://x.com/cortensor/status/1897748997911331213>

### Infographic #29: Synthetic Data Creation with PoUW

* <https://x.com/cortensor/status/1898114756709658942>

### Infographic #30: Blockchain Layers - L1 Security Gate

* <https://x.com/cortensor/status/1898834637738361297>

### Infographic #31: Blockchain Layers - L3 Private Vault

* <https://x.com/cortensor/status/1899190437082210793>

### Infographic #32: Data Management - Decentralized Storage Process

* <https://x.com/cortensor/status/1899549378911862867>

### Infographic #33: Blockchain Layers - Three-Layer Architecture

* <https://x.com/cortensor/status/1900026091248791930>

### Infographic #34: Blockchain Layers - L2 Busy Hub

* <https://x.com/cortensor/status/1900264360762908806>

### Infographic #35: Blockchain Layers - Multi-Layered Architecture

* <https://x.com/cortensor/status/1900641487660216680>

### Infographic #36: Blockchain Layers - Data Flow Across Layers

* <https://x.com/cortensor/status/1901164376922710352>

### Infographic #37: PoUW State Machine - Task Management Sequence

* <https://x.com/cortensor/status/1901409442954183021>

### Infographic #38: Mining Process - Incentive & Performance

* <https://x.com/cortensor/status/1901716975493234965>

### Infographic #39: Mining Process - Four-Phase Progression for Task

* <https://x.com/cortensor/status/1902222813597208944>

### Infographic #40: Consensus - Validation Process - PoI & PoUW

* <https://x.com/cortensor/status/1902806522444517887>

### Infographic #41: Distributed System Scaling - Efficient Sampling

* <https://x.com/cortensor/status/1903426500436881427>

### Infographic #42: Mining Process - Core Components

* <https://x.com/cortensor/status/1904162307028197849>

### Infographic #43 - Proof of Inference: Building Trust and Reliability

* <https://x.com/cortensor/status/1905110630782419176>

### Infographic #44: Proof of Inference - Enhancing Decision-Making

* <https://x.com/cortensor/status/1905684852109922548>

### ~~Infographic #45: Proof of Inference - AI Agent Enhancement~~

* [~~https://x.com/cortensor/status/1876567735280509094~~](https://x.com/cortensor/status/1876567735280509094)

### ~~Infographic #46: Proof of Inference - Capability Enhancement for AI Agents~~

* [~~https://x.com/cortensor/status/1876925055726432436~~](https://x.com/cortensor/status/1876925055726432436)

### Infographic #47: Proof of Inference - Impact on Decentralized AI

* <https://x.com/cortensor/status/1906504284633714879>

### Infographic #48: Task Flow - User Requests

* <https://x.com/cortensor/status/1906935447554777488>

### Infographic #49: Data Management - Privacy, Scalability & Enterprise

* <https://x.com/cortensor/status/1907546101231792383>

### Infographic #50: Blockchain Layers - L1 Security Gate

* <https://x.com/cortensor/status/1908343719998439785>

### Infographic #51: Task Flow - User Task & Data Flow

* <https://x.com/cortensor/status/1908835597508345971>

### Infographic #52: Module IAM - Identity & Access Process

* <https://x.com/cortensor/status/1909398623760294350>

### Infographic #53: Module IAM - Workflow

* <https://x.com/cortensor/status/1909899032832737422>

### Infographic #54: Module IAM - Workflow

* <https://x.com/cortensor/status/1910400619787292710>

### Infographic #55: Module – Node Reputation

* <https://x.com/cortensor/status/1910825986964545685>

### Infographic #56: Module Session & Session Queue

* <https://x.com/cortensor/status/1911908112644346364>

### Infographic #57: Module – ACL (Access Control Layer)

* <https://x.com/cortensor/status/1912649220231991742>

### Infographic #58: Core Concepts – Cortensor’s Foundational Components

* <https://x.com/cortensor/status/1913738372771992057>

### Infographic #59: Scalability – Session & Task Flow

* <https://x.com/cortensor/status/1914794314221412356>

### Infographic #60: Proof of Useful Work – Synthetic Data Generation

* <https://x.com/cortensor/status/1915904948963053639>

### Infographic #61: Core Concepts – Value Propositions

* <https://x.com/cortensor/status/1916681917656948882>

### Infographic #62: Module – Node Reputation

* <https://x.com/cortensor/status/1916951602868719651>

### Infographic #63: Blockchain Layers – L2: The Busy Hub

* <https://x.com/cortensor/status/1917341119832285410>

### Infographic #64: Mining Process – Simplified Overview

* <https://x.com/cortensor/status/1917913522543141350>

### Infographic #65: Cognitive Module – Workflow

* <https://x.com/cortensor/status/1918415290347753606>

### Infographic #66: Core Principles – Precision, Security & Fairness

* <https://x.com/cortensor/status/1919221162632216664>

### Infographic #67: Proof of Inference - Value Propositions

* <https://x.com/cortensor/status/1919535551038067155>

### Infographic #68: Real-World Use Cases for Decentralized AI

* <https://x.com/cortensor/status/1919900761145987448>

### Infographic #69: Key Features of Cortensor – The Linux of AI

* <https://x.com/cortensor/status/1920236700602925296>

### Infographic #70: Core Concepts – Value Propositions

* <https://x.com/cortensor/status/1920600594055925900>

### Infographic #71: Session Module – The Inference Strategist

* <https://x.com/cortensor/status/1920973210511962254>

### Infographic #72: Session Queue – The Inference Pipeline

* <https://x.com/cortensor/status/1921308324735386012>


# Designs - WIP


# \[WIP] Agentic

Cortensor as the Backbone of Decentralized AI Infrastructure

**Status:** Conceptual Architecture (Post-Mainnet Vision)\*\*\
**Related Modules:** `Session`, `Validator`, `SessionQueueValidation`, `ERC-8004`\
**References:**\
<https://docs.cortensor.network/technical-architecture/erc-8004-in-context-from-trust-fabric-to-execution-fabric-draft>\
<https://docs.cortensor.network/technical-architecture/sessionqueuevalidation-taskroot-sessionroot-for-erc8004-compatibility-draft>

***

### **Overview**

Cortensor is built as the **execution backbone for decentralized AI** — a **model-agnostic, verifiable inference infrastructure** capable of routing, executing, and validating AI workloads across distributed hardware.

As the network transitions toward Mainnet, this foundation will naturally evolve into a broader **Agentic Layer** — not by replacing the core network, but by **extending it upward**.\
\
This layer will enable agents and autonomous systems to run directly on Cortensor’s decentralized runtime, inheriting the same trust, proof, and validation mechanisms that power inference today.

***

### **Purpose**

The Agentic initiative builds upon Cortensor’s existing capabilities — **sessions, routing, validation, and proof of work** — to enable the next phase of decentralized AI: agent-native operations.

Its goals are to:

1. **Reinforce Cortensor’s role as infrastructure** — a model-agnostic, verifiable compute fabric that powers decentralized inference and validation at scale.
2. **Bridge trust and execution** — linking ERC-8004’s *trust fabric* (identity, reputation, validation) with Cortensor’s *execution fabric* (inference, proofs, and payments).
3. **Offer an Agent SDK as an extension layer** — giving developers a toolkit to build autonomous, verifiable, privacy-preserving agents that run natively on Cortensor infrastructure.

***

### **Core Concepts**

#### **1. Model-Agnostic Inference Infrastructure**

At its core, Cortensor remains **model-agnostic** — supporting any compatible AI model, including LLaMA, Mistral, Falcon, DeepSeek, or OpenAI.\
This flexibility ensures the network is **not bound to any vendor or model provider**, making it a truly open execution layer for distributed intelligence.

The Agentic direction doesn’t change this foundation — it **extends** it.\
Agents built on Cortensor will simply utilize the same primitives (Session, Validator, Proof) that already underpin inference and validation today.

***

#### **2. Agent SDK (Built on Top of Cortensor)**

The upcoming **Cortensor Agent SDK** is an **additional developer offering**, designed to make it easier to build, orchestrate, and validate agent workloads using Cortensor’s underlying infrastructure.

It does **not replace** the core network — it **interfaces** with it.

**Planned capabilities include:**

* **Session integration** – Instantiate and manage decentralized sessions for agent tasks.
* **Proof generation** – Automatically emit TaskRoot and SessionRoot proofs for every execution.
* **Model abstraction** – Invoke any model backend seamlessly (local, on-chain, or external).
* **Cross-agent messaging** – Use ERC-8004 Identity and Validation registries for peer coordination.
* **Privacy-preserving mode** – Optional encrypted task execution using Cortensor’s three-party encryption protocol.
* **On-chain reputation linkage** – Write validation results and reliability data into ERC-8004’s Reputation registry.

**Outcome:**\
The SDK makes Cortensor’s infrastructure **programmable** for developers — enabling them to create verifiable, interoperable agents that operate directly on the decentralized compute fabric.

***

#### **3. ERC-8004 Alignment**

ERC-8004 defines the **trust layer** for agents — specifying *who* an agent is and *why* they can be trusted.\
Cortensor provides the **execution layer** — *how* work is done, *how* it’s verified, and *where* the proof resides.

| **ERC-8004 Registry** | **Cortensor Counterpart**                       | **Purpose**                                                                                 |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Identity              | IAM / SessionID                                 | Establishes verified agent or node identity through Cortensor’s session and access control. |
| Reputation            | NodeReputation / SessionReputation              | Tracks reliability and historical performance from validated work.                          |
| Validation            | SessionQueueValidation (TaskRoot / SessionRoot) | Anchors verifiable compute proofs as standardized `DataHash` records on-chain.              |

Through this alignment, Cortensor becomes the **execution substrate** for ERC-8004 agents — providing the infrastructure they rely on for verifiable work, regardless of how or where they’re deployed.

***

#### **4. Agentic Services (Built on Cortensor)**

Once Mainnet is operational, Cortensor will begin exposing **Agentic Services** powered by its decentralized runtime.\
These services are built on top of existing inference and validation systems — extending them into agent-level functionality.

| **Service**                      | **Description**                                                                                             |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Agent Hosting**                | Deploy autonomous agents across miner nodes, maintaining verifiable inference sessions.                     |
| **Autonomous Validation**        | Validator agents automatically execute PoI and PoUW checks for peer outputs.                                |
| **Reputation Oracle**            | Aggregates trust data (NodeReputation, SessionReputation, ValidationResponse) into global reputation feeds. |
| **Privacy-Preserving Execution** | Leverages three-party encryption for confidential agent workloads.                                          |
| **Cross-Agent Collaboration**    | Enables agent-to-agent task delegation and cooperative validation through SessionQueue and proof sharing.   |

These services don’t redefine Cortensor — they **amplify it**, showing how verifiable inference naturally extends to verifiable autonomy.

***

#### **Evolution Roadmap**

| **Phase**        | **Focus**                        | **Description**                                                                                   |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Testnet**      | Validation & Privacy Foundations | Expand PoI / PoUW logic, integrate privacy primitives, and stabilize validator runtime.           |
| **Mainnet Lite** | SDK Alpha                        | Release early Cortensor Agent SDK with session routing, validation APIs, and developer templates. |
| **Mainnet Full** | Agent Economy Activation         | Integrate ERC-8004 registries, enable cross-agent validation, and reputation anchoring.           |
| **Beyond & GA**  | Agent-Native COR Rollup          | Dedicated L3 chain optimized for agent state, validation proofs, and micro-payments.              |

***

#### **Architecture Flow**

```
Agent SDK (optional layer)
   │
   ▼
Cortensor Session → Miner Execution → TaskRoot (Proof)
   │                                │
   └──────────────→ SessionRoot (Rolling Ledger)
                                   │
                                   ▼
                     Validator (PoI / PoUW)
                                   │
                                   ▼
                 ERC-8004 Validation Registry
                         ↕
           Identity / Reputation / Validation Loops
```

***

#### **Why It Matters**

Cortensor’s mission is not to build “just another agent platform” —\
it is to remain the **trust backbone of decentralized AI**, enabling *any* model, *any* agent, and *any* developer to participate in a verifiable, composable ecosystem.

The **Agent SDK** is an *extension* of that vision — a bridge between Cortensor’s decentralized infrastructure and the emerging agent economy.

**In essence:**

> Cortensor provides the foundation — the verifiable, model-agnostic execution layer.\
> The Agent SDK makes it usable — a toolkit for agents to interact, collaborate, and prove their work.
>
> Together, they form the infrastructure spine of the **trustless, agentic AI future**.


# ERC-8004 in Context: From Trust Fabric to Execution Fabric (Draft)

ERC-8004 defines a **trust fabric for autonomous agents** by standardizing how agents can be discovered, identified, and validated across organizations without pre-existing trust.

However, the standard **stops short of execution**. It specifies *who an agent is*, *why they might be trusted*, and *where validation records live*—but not *how tasks are executed or verified*.

**Cortensor supplies this missing execution layer.** By routing inference workloads across decentralized nodes and attaching verifiable proofs, Cortensor provides the *how + proof* that complements ERC-8004’s *who + why*.

References:

* ERC-8004 EIP: <https://eips.ethereum.org/EIPS/eip-8004>
* A2A Protocol overview (Google): <https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/>
* A2A Extensions (Google): <https://developers.googleblog.com/en/a2a-extensions-empowering-custom-agent-functionality/>
* A2A Intro Codelab: <https://codelabs.developers.google.com/intro-a2a-purchasing-concierge>
* Ethereum Magicians Discussion: <https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098> and <https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098?page=2>

***

#### What ERC-8004 Defines

* **Identity Registry** – establishes agent identity across organizations.
* **Reputation Registry** – records why an agent is trustworthy (history, endorsements, scores).
* **Validation Registry** – anchors validation events on-chain for transparency.

The EIP explicitly leaves application logic **off-chain**: execution, inference, and verification methods are not specified. Validation is just a minimal on-chain record — it could be powered by a **TEE attestor**, a **stake committee**, or even a **single centralized judge**.

***

#### Where Cortensor Fits

**1. From&#x20;*****Trust*****&#x20;→&#x20;*****Execution with Proofs***

* **Identity / Reputation (ERC-8004) → Job Admission (Cortensor)**\
  Cortensor routers can check ERC-8004 identity/reputation as a policy input before dispatching tasks.
* **Validation (ERC-8004) → Proof of Inference (Cortensor)**\
  After execution, Cortensor can emit verifiable artifacts (e.g., output hashes, PoI/PoUW receipts) and anchor those references to the ERC-8004 Validation registry.

**2. Turning Registries into a Compute Market**

* Cortensor routes workloads across heterogeneous hardware (edge devices → GPU clusters).
* Results are verified via **Proof of Inference (PoI)** and **Proof of Useful Work (PoUW)**.
* Outcomes and verifier assessments can be written back to ERC-8004 Reputation to update credibility with evidence.

**3. Policy & Reliability Beyond Spec**

* ERC-8004 is minimal by design. Cortensor enforces **off-chain policies** — SLA, model/version allowlists, latency/energy thresholds — while anchoring validation signals on-chain.
* This respects the EIP’s minimalism while delivering **real-world reliability**.

***

#### Centralized Judge vs. Cortensor Validator

| **Validation Mode** | **How It Works**                                                                            | **Limitations**                                   | **Cortensor Alternative**                                          |
| ------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| Centralized Judge   | A single entity (or LLM API) decides if results are valid and writes to Validation registry | Bottlenecked, trust rests in one provider         | Tasks routed across many nodes, results verified via PoI/PoUW      |
| TEE Attestor        | Hardware enclave attests to output correctness                                              | Requires hardware trust & supply-chain guarantees | Verifiable inference without hardware lock-in                      |
| Stake Committee     | Group of stakers validate and write to registry                                             | Can be captured or cartelized                     | Open, decentralized miner/oracle network with cryptographic proofs |

**Key point:** ERC-8004 doesn’t force which “judge” is used. Cortensor provides a **trustless, decentralized judge**, ensuring validation is both distributed and verifiable.

***

#### Mental Model

* **ERC-8004 = Trust Fabric**: identity, reputation, validation registries.
* **Cortensor = Execution Fabric**: routing, inference, verification, privacy.
* **Loop**: *Who + Why (ERC-8004) → How + Proof (Cortensor) → Updated Reputation (ERC-8004).*

***

#### Why It Matters

Without Cortensor, ERC-8004-enabled agents could still rely on **centralized inference providers**, leaving the “last mile” centralized.

With Cortensor:

* Inference is **decentralized and verifiable**.
* Results are tied back to **ERC-8004 registries** for trust anchoring.
* Agents don’t just interoperate—they **execute and prove work trustlessly**.

This unlocks a **true agent economy**, where identity, execution, and reputation are fully linked.

***

#### Developer Integration Pattern (Conceptual)

1. **Read Identity/Reputation** from ERC-8004.
2. **Route Task** through Cortensor’s decentralized inference fabric.
3. **Generate Proofs** (PoI receipts, PoUW quality scores).
4. **Anchor Validation** back into ERC-8004’s Validation registry.

This pattern ties **on-chain trust** directly to **off-chain execution and verification**.

***

⚠️ **Status:** ERC-8004 is about a month old and under active community discussion. Cortensor’s execution layer is not part of the spec but provides a **practical path** to close the trust → execution loop with verifiable inference.


# SessionQueueValidation: TaskRoot & SessionRoot for ERC-8004 Compatibility (Draft)

**Status:** Conceptual Design Phase\
**Related Modules:** `SessionQueue`, `Validator`, `QuantitativeStats`, `QualitativeStats`\
**Reference:** <https://x.com/cortensor/status/1974765387339473150>

***

### **Overview**

The **SessionQueueValidation** module is being extended to introduce **TaskRoot** and **SessionRoot** structures — a cryptographic framework for tracking verifiable task completion and continuous session evolution.\
This design aims to make Cortensor’s **inference validation** interoperable with **ERC-8004’s Validation Registry**, enabling standardized proof exchange across agent and compute networks.

Cortensor sessions are continuous and open-ended.\
Each **task** executed within a session becomes an **atomic proof unit**, while the session itself evolves as a **rolling ledger of trust**.

***

### **Conceptual Design**

#### **TaskRoot (Sealed Proof)**

* Each task request within a session is executed by multiple miners.
* Their outputs are hashed, verified, and aggregated into a **Merkle root (TaskRoot)** that cryptographically commits to all miner results for that task.
* Once sealed, a TaskRoot serves as an immutable proof artifact — representing one verifiable checkpoint of inference.

**Purpose:**\
Provides tamper-evident validation for a single task execution.\
Used by validators for replay verification (e.g., **Proof of Inference (PoI)** or **Proof of Useful Work (PoUW)**).

***

#### **SessionRoot (Rolling Ledger)**

* As each TaskRoot is sealed, it is appended to a **rolling Merkle accumulator** called the **SessionRoot**.
* The SessionRoot evolves as new tasks are completed, forming a cumulative state that represents all verified tasks under one session.
* This enables perpetual sessions without closure after each task, maintaining continuity for long-lived agent or application processes.

**Purpose:**\
Maintains a verifiable, cumulative record of all TaskRoots under a given session.\
Acts as a **living commitment** to the full session history.

***

### **Proposed ERC-8004 Mapping**

The design aligns Cortensor’s validation structure with **ERC-8004’s trust fabric**, allowing Cortensor sessions to function as verifiable agent servers under the ERC-8004 model.

| **ERC-8004 Field** | **Cortensor Equivalent** | **Description**                                                                                                          |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `AgentServerID`    | `SessionID`              | Represents the aggregated “agent server.” Abstracts miner identities internally but exposes a unified external identity. |
| `AgentValidatorID` | `Validator / Oracle`     | Executes PoI / PoUW checks and records ValidationResponse events to the ERC-8004 Validation Registry.                    |
| `DataHash`         | `TaskRoot / SessionRoot` | Cryptographic commitment referencing either a single verified task or the cumulative session state.                      |

**Key Relationship:**

* **TaskRoot** → atomic proof of a single inference.
* **SessionRoot** → rolling ledger of all inferences under a session.\
  Together, these structures enable **cross-network trust interoperability** — allowing Cortensor proofs to be read, verified, or referenced by external ERC-8004 registries.

***

### **Internal Data Model**

Each **TaskRoot** is derived from a canonical hashing schema that records the full provenance of a task:

```
(taskID, minerID, modelID, inputHash, outputHash, metadata)
```

**Fields:**

* **taskID:** Unique identifier of the inference task.
* **minerID:** Node(s) performing the work.
* **modelID:** Model or architecture used for inference.
* **inputHash:** Cryptographic hash of the input (prompt, configuration).
* **outputHash:** Hash of the generated output tensor or result.
* **metadata:** Optional contextual data (timestamps, environment info, scoring).

Merkle leaves are constructed from this structure.\
The resulting **TaskRoot** becomes a deterministic commitment to all miner outputs, verifiable by validators or external auditors.

***

### **Validator Interaction**

#### **1. ValidationRequest**

Validators initiate verification using a `DataHash` (TaskRoot or SessionRoot) to request validation of a given inference.

#### **2. Verification Process**

Validators perform:

* **Proof of Inference (PoI):** embedding-distance checks for result consistency.
* **Proof of Useful Work (PoUW):** LLM-based evaluations of result quality and utility.

#### **3. ValidationResponse**

Upon completion, validators submit **ValidationResponse** entries into the **ERC-8004 Validation Registry**, anchoring Cortensor proofs on a common trust layer for transparent, interoperable validation.

***

### **Why It Matters**

* **Reproducibility:** Every inference becomes a sealed, replayable proof unit.
* **Continuity:** SessionRoot preserves long-running, evolving workloads.
* **Interoperability:** Bridges Cortensor’s decentralized validation with ERC-8004’s standardized trust registries.
* **Transparency:** Enables external audits, proof replay, and cross-network reputation scoring.

Together, **TaskRoot** and **SessionRoot** form a unified framework for **verifiable, evolving, and auditable inference**, anchoring decentralized AI execution in a shared validation ecosystem.

***

### **Next Steps**

1. Prototype canonical hashing schema `(taskID, minerID, modelID, inputHash, outputHash, metadata)` for Merkle generation.
2. Integrate **ValidationRequest / ValidationResponse** into Cortensor’s PoI loop.
3. Map **SessionID / ValidatorID** to ERC-8004 Identity Registry for agent reputation linkage.
4. Simulate **rolling SessionRoot updates** and test replay validation.
5. Benchmark **multi-validator performance and gas costs** for potential cross-chain anchoring.

***

### **Architecture Flow**

```
┌───────────────────────────────┐
│      Task Execution (Miners)  │
└──────────────┬────────────────┘
               │
               ▼
      Hash inputs/outputs → Build Merkle leaves
               │
               ▼
       TaskRoot (sealed proof per task)
               │
               ▼
   SessionRoot (rolling ledger of all TaskRoots)
               │
               ▼
     Validator performs PoI / PoUW verification
               │
               ▼
   ValidationResponse → ERC-8004 Validation Registry
```

**Flow Summary:**\
Each task produces a **TaskRoot** as a sealed proof.\
The **SessionRoot** continuously aggregates all TaskRoots, forming a rolling ledger of trust.\
Validators then verify and anchor these proofs into **ERC-8004’s on-chain Validation Registry**, connecting Cortensor’s decentralized execution fabric with the emerging agent trust fabric.


# Corgent Overview - Virtual Trust Oracle on Cortensor

### Prerequisites / Glossary (Read This First)

#### What is GAME?

**GAME** is Virtual’s Agent SDK and execution framework — the **brain + orchestration layer** for Virtual agents.

In GAME:

* **Agent** = planner / reasoner that decides goals and next steps
* **Workers** = execution units selected by the Agent
* **Functions** = real external calls made by Workers\
  (APIs, tools, other agents, or marketplace services)

So the loop is:\
**Agent plans → Worker executes → Function calls real services → Agent continues.**

***

#### What is ACP?

**ACP** is Virtual’s marketplace / commerce layer for agents.\
It enables buying, selling, and verifying agent services.

In ACP:

* **Buyer agent** requests work or results
* **Seller agent** provides work/results
* **Evaluator / Oracle agent** verifies correctness or resolves disputes

ACP is where agents “trade tasks,” and need **trusted verification** if outcomes are disputed or high-stakes.

***

#### What is the Cortensor Router Node (v1)?

The **Cortensor Router Node (v1)** is Cortensor’s **client-facing task broker**.\
It accepts user/agent tasks and routes them into Cortensor’s decentralized inference network.

Router v1 does:

* receives tasks from clients/apps
* opens/uses a **Session**
* sends tasks into the **Session Queue**
* dispatches work to **miners**
* collects outputs + proof signals
* returns results to the caller

Think of Router v1 as:\
**“REST task gateway → decentralized inference.”**

***

#### Router Evolution → Corgent

Corgent is the **agentic evolution of Router Node capabilities**, productized as a Virtual-native oracle agent.

**Current and planned Router path:**

1. **Router Node v1 (today)**
   * REST-based task broker
   * handles delegation for `/completions`-style inference
2. **Router Node v1 (experimental add-ons)**
   * **x402 experiments already live on some Router endpoints**\
     → per-router pay-per-call inference for Web2/Web3 clients
   * **MCP server running as a separate experimental process**\
     → “agent-callable Router” via MCP + HTTP
3. **Router Node v1.5 (“Router Agent”)**
   * MCP **merged into Router Node**
   * x402 standardized across Router inference endpoints
   * Router becomes a **first-class agent surface**
   * exposes **agent-ready `/completions`**
4. **Router Node v1.6 (ERC-8004 Agent-Ready Router)**
   * adds `/validate` endpoint
   * Router can now do:
     * **Task Delegation** (`/completions`)
     * **Task Validation** (`/validate`)
   * powered by PoI / PoUW trust rails
   * **ERC-8004-ready in production:**\
     Any developer, agent builder, or node operator can **spawn their own Router Agent v1.6** and register it as an ERC-8004 service.\
     This lets them offer inference + validation services directly into the ERC-8004 ecosystem by leveraging **Router Node surfaces + Cortensor compute and proofs**.
5. **Router Node v2.0 = Corgent**
   * Router’s delegation + validation capability becomes a **full Virtual-native oracle agent**
   * Corgent wraps Router v1.6 surfaces with:
     * policy selection
     * miner redundancy
     * PoI/PoUW interpretation
     * structured verdicts
     * ACP settlement logic
   * effectively: **the Router Agent matured into an oracle product**

**In short:**\
Router evolves into an agent surface (v1.5) → gains ERC-8004 delegation + validation (v1.6) → becomes Corgent (v2.0) inside Virtual.

***

### Overview

Corgent is a Virtual Ecosystem service agent built on top of the Cortensor Network.\
It makes Cortensor usable inside Virtual as a **task delegation + task verification oracle**, so agents can rely on **verifiable inference** instead of trusting a single model run or a single agent’s output.

At a high level:

**GAME decides → Corgent delegates/validates → Cortensor computes/proves → Corgent returns oracle verdict → GAME continues.**

***

### TL;DR

Corgent is the Virtual ecosystem’s trust oracle:

* **Delegation-as-a-Service:** send tasks to Cortensor miners reliably.
* **Validation-as-a-Service:** verify agent outputs using PoI/PoUW.
* **Arbitration-as-a-Service:** resolve disputes with oracle-grade replays.

It’s not a “thinking agent.” It’s a **trust + orchestration layer.**

***

## WHAT

### What Corgent is

Corgent is a **Client/Router-side oracle agent inside Virtual.**\
It doesn’t do heavy autonomous reasoning by itself, and it’s not part of Cortensor’s miner or validator sets.

Instead, Corgent’s job is to:

1. **Receive tasks or claims from other agents**\
   *(typically GAME Workers/Functions or ACP buyers/sellers)*
2. **Delegate inference to Cortensor’s decentralized compute network**\
   *(Router → Session Queue → Miners)*
3. **Oracle-validate results using Cortensor’s proof rails**\
   *(PoI / PoUW, reputation, integrity checks)*
4. **Return a structured oracle verdict**
   * `VALID`
   * `INVALID`
   * `RETRY`
   * `NEEDS_SPEC`

***

### What Corgent is not

* **Not a planner / goal generator**\
  *(GAME Agent does planning.)*
* **Not a miner**\
  *(Cortensor miners do inference.)*
* **Not the base Cortensor validator set**\
  *(Network validators enforce protocol rules.)*
* **Not a creative agent by default**\
  Corgent is a **trust + orchestration productized layer**, not a “creative brain.”

***

### What Corgent provides to the Virtual Ecosystem

Think of Corgent as a **“trust oracle service”** any Virtual Agent can call:

* **Delegation-as-a-Service**\
  “Run this task on Cortensor with reliability tier X.”
* **Validation-as-a-Service**\
  “Verify that this other agent’s result is correct/useful.”
* **Arbitration-as-a-Service**\
  “Resolve a dispute with an oracle-grade replay.”

***

## HOW

### How Corgent fits with GAME (Virtual Agent SDK)

* **GAME = brain + orchestration**
  * Agent plans
  * Workers execute
  * Functions are real calls
* **Cortensor = distributed inference + proofs**
  * Router → Session Queue → Miners
  * PoI / PoUW + reputation + integrity signals
* **Corgent = oracle wrapper**
  * Exposed as a Worker/Function target or ACP seller
  * Decides compute + validation policy
  * Interprets proofs
  * Returns verdicts

**Layering:**

**GAME decides → Corgent delegates/validates → Cortensor computes/proves → Corgent returns oracle output → GAME continues.**

***

### How Corgent uses Cortensor (conceptual)

Corgent behaves like a smart client on Cortensor:

* Creates/uses sessions (prepaid budgets)
* Submits tasks through Router Nodes
* Requests redundancy (N runs in parallel)
* Collects miner outputs + proof signals
* Applies oracle logic:
  * PoI rerun comparison
  * N-of-M consensus clustering
  * Spec/schema checks
  * Usefulness scoring (PoUW-style)
  * Reputation weighting
  * Integrity checks (commit/reveal alignment)

***

### How Corgent decides validation depth (policy)

Corgent selects a tier per task:

* **Fast tier**
  * 1 miner
  * light usefulness checks
* **Safe tier**
  * 3 miners
  * PoI consensus + usefulness scoring
* **Oracle-grade tier**
  * 5 miners
  * PoI + strict usefulness + diversity sampling
  * stake/reputation weighting

**Adaptive mode (optional):**

* start cheap (1 miner)
* escalate redundancy when confidence is low

***

## FLOWS

### Flow A — Delegation-as-a-Service (Compute Oracle)

**Goal:** Another agent wants compute done reliably.

1. GAME Agent decides it needs task X.
2. Agent selects Worker (e.g., SummarizeWorker).
3. Worker calls Function:\
   `delegate_to_corgent(task, policy="safe")`
4. Corgent chooses Cortensor policy (model, redundancy, tier).
5. Corgent submits task to Cortensor session via Router.
6. Cortensor dispatches to miners (parallel if redundancy > 1).
7. Miners return results + proof signals.
8. Corgent validates + selects consensus/best output.
9. Corgent returns: result + confidence + evidence.
10. Worker returns result to Agent.
11. Agent continues planning.

**In one line:**\
**GAME Worker → Corgent → Cortensor parallel inference → oracle-validated output → back to GAME**

***

### Flow B — Validation-as-a-Service (Result Oracle)

**Goal:** Another agent’s claim needs verification.

1. GAME Agent receives a claimed output.
2. Agent selects Worker (e.g., ValidationWorker).
3. Worker calls Function:\
   `validate_with_corgent(task, claimed_result)`
4. Corgent selects validation pattern:
   * deterministic → PoI rerun & compare
   * nondeterministic → N-of-M consensus
   * structured → spec checks always-on
5. Corgent triggers Cortensor rerun/consensus if needed.
6. Corgent evaluates proofs + reputation + spec.
7. Corgent returns verdict with confidence + reason.
8. Worker forwards verdict to Agent.
9. Agent accepts / retries / escalates.

**In one line:**\
**GAME Worker → Corgent → Cortensor rerun/consensus → oracle verdict → back to GAME**

***

### Flow C — Arbitration-as-a-Service (Dispute Oracle)

**Goal:** Buyer and seller disagree; need binding truth.

1. ACP buyer files dispute to Corgent.
2. Corgent escalates to oracle-grade tier.
3. Cortensor runs 5 miners with diversity sampling.
4. Corgent derives stable consensus + usefulness checks.
5. Corgent compares seller output vs oracle consensus.
6. Returns binding verdict for settlement.

***

## EXAMPLES

### Tiny Delegation Example

* Agent wants a high-trust summary.
* Worker calls:\
  `delegate_to_corgent(task, policy="safe")`
* Corgent uses redundancy = 3.
* Cortensor runs 3 miners in parallel.
* Corgent returns oracle-validated summary.
* Agent moves on.

***

### Tiny Validation Example

* Agent receives another agent’s output.
* Worker calls:\
  `validate_with_corgent(task, claimed_result)`
* Corgent reruns task on Cortensor (PoI echo).
* Compares rerun vs claimed.
* Returns verdict: `VALID / INVALID / RETRY`.

***

### Practical Validation Example 1 — Structured tool-call check

**Task:** “Return JSON for tool create\_event(title, start, end).”\
**Claimed result:** `{title:"demo", end:"tomorrow"}`

**Corgent does:**

* runs schema check locally → fails
* returns `INVALID` with retry guidance

**Output:**

* `status: INVALID`
* `reason: missing field + datetime format violation`
* `retry: required fields + ISO-8601 format`

***

### Practical Validation Example 2 — Consensus verification for LLM text

**Task:** “Write 5 bullets summarizing competitor landscape.”\
**Claimed result:** seller bullets

**Corgent does:**

* requests 3 Cortensor runs
* PoI similarity clusters stable consensus
* checks seller alignment
* if outlier → `RETRY`

**Output:**

* `status: RETRY`
* `evidence: consensus_outlier`
* `retry: include competitors A/B/C, keep ≤5 bullets, cite sources`

***

### Practical Delegation Example — Adaptive redundancy

**Task:** “Research and summarize topic X.”\
**Policy:** adaptive

**Corgent does:**

* starts with 1 miner
* confidence low → escalates to 3 miners automatically
* returns stable consensus

**Benefit:**

* cheap on easy tasks
* oracle-safe on hard tasks
* no manual tuning by GAME

***

### Practical Arbitration Example — Buyer vs seller dispute

**Task:** “Generate 10 product names with constraints.”\
**Issue:** buyer claims seller ignored constraints

**Corgent does:**

* escalates to oracle-grade (5 miners)
* derives consensus
* compares seller vs consensus + spec
* issues binding decision

**Output:**

* `VALID seller` or `INVALID seller`
* evidence trail: PoI cluster + usefulness score
* final decision used for settlement

***

### One-sentence takeaway

**Corgent is the Virtual Ecosystem’s trust oracle: GAME asks, Cortensor computes, Corgent proves and judges.**


# Why Corgent Matters (for Virtual + Cortensor)

Corgent is more than a single app — it’s a **missing trust primitive** for agent ecosystems. Virtual agents need reliable execution and verifiable outcomes, and Cortensor needs real agent-native demand loops. Corgent connects both.

#### Clarification: Corgent complements GAME (it doesn’t replace it)

Corgent is **not meant to replace GAME’s planning or reasoning logic**.\
GAME remains the “brain” that decides goals, tracks context, and chooses what to do next.

Instead, Corgent is an **optional trust tool** Virtual agents can call *when they need higher reliability*:

* **Agents choose when to use Corgent**\
  Low-stakes tasks can run normally. High-stakes or uncertain tasks can be verified before acting.
* **Reliable decisions, not autonomous thinking**\
  Corgent doesn’t generate goals or strategies. It provides **validated evidence** so agents can decide safely.
* **Action validation & confirmation**\
  Agents can use Cortensor’s **redundant miners + PoI/PoUW** through Corgent to:
  * confirm an action is correct before executing
  * verify prior steps in multi-agent workflows
  * reduce hallucination risk in critical paths
  * ensure outputs meet constraints before committing

**In short:** GAME thinks and decides. **Corgent proves and confirms when trust matters.**

***

#### Why it’s important for the Virtual Ecosystem

Virtual is an agent-first environment: agents plan, call tools, buy services, and depend on other agents’ outputs. Without a trust layer, the same LLM failure modes show up — just amplified across multi-agent chains.

* **Agent outputs aren’t inherently trustworthy**\
  One agent can hallucinate, ignore constraints, or return low-quality results. Corgent gives Virtual a **default verification oracle**.
* **Multi-agent systems need a “truth referee”**\
  When agents depend on other agents, errors compound. Corgent lets agents validate **task results or intermediate reasoning steps** before continuing.
* **ACP marketplaces require credible dispute resolution**\
  ACP introduces buyers/sellers/evaluators, but markets can’t scale without trusted arbitration. Corgent provides **oracle-grade replay + binding verdicts** for settlement.
* **Trust-minimized agent commerce by default**\
  Agents don’t need to trust a single model run or a single seller. They can trust **redundant compute + PoI/PoUW validation**, making agent services safer to consume.

***

#### Why it’s important for the Cortensor Network

Corgent translates Cortensor’s core strengths into **real agent-native demand**, which is where most Web3 inference usage will come from.

* **Turns Cortensor into a verifiable agent backend**\
  Not just inference-as-a-service, but **delegation + validation-as-a-service** for autonomous agents.
* **Creates real Web3 consumption loops**\
  Virtual becomes the primary distribution surface for Web3 agent traffic. Corgent routes that traffic into Cortensor, making Cortensor the **compute + verification fabric** for agent economies.
* **Hardens PoI/PoUW under real workloads**\
  Validation rails only mature with diverse, adversarial, real-world tasks. Corgent drives high-volume **redundant inference + usefulness evaluation**, strengthening Cortensor’s trust system.
* **Enables ERC-8004 service expansion**\
  Router v1.6 is ERC-8004 agent-ready, so any developer or node operator can spawn their own Router Agent to offer services into the ERC-8004 ecosystem using Cortensor compute and proofs. Corgent is the flagship example of that path.

***

#### One-line summary

**Corgent gives Virtual agents a trust oracle, and gives Cortensor an agent-native demand engine — making both ecosystems stronger together.**


# \[WIP] Corgent API Spec (Draft v0.1)

*THIS SPEC IS A DRAFT. NAMES AND FIELDS MAY CHANGE AS VIRTUAL SDK AND CORTENSOR TESTNET PHASE 3–4 HARDEN.*

### 0) Purpose

Corgent is a **Virtual ecosystem service agent** that provides:

1. **Delegation-as-a-Service (Compute Oracle)**
2. **Validation-as-a-Service (Result Oracle)**
3. **Arbitration-as-a-Service (Dispute Oracle)**

Corgent sits **client/router-side** and uses Cortensor to run redundant inference and produce PoI/PoUW-backed verification artifacts. ([Cortensor](https://docs.cortensor.network/technical-architecture/node-lifecycle?utm_source=chatgpt.com))

***

### 1) Surfaces

Corgent exposes two integration surfaces:

#### A. GAME Worker/Function Surface (Virtual SDK)

Corgent is callable as a **Function target** from a GAME Worker. The Virtual SDK is built around **Agent → Worker → Function**. ([GitHub](https://github.com/Virtual-Protocol/virtuals-python?utm_source=chatgpt.com))

#### B. ACP Marketplace Surface (Virtual ACP)

Corgent can act as an **ACP Evaluator / Oracle Seller**:

* Buyers request verification or arbitration.
* Sellers may optionally request pre-verification.\
  ACP role model: Buyer (Client), Seller (Provider), optional Evaluator. ([Virtuals Protocol](https://whitepaper.virtuals.io/acp-product-resources/acp-concepts-terminologies-and-architecture?utm_source=chatgpt.com))

***

### 2) Core Concepts

#### 2.1 Task

A unit of work to run or verify.

```json
{
  "task_id": "uuid",
  "type": "inference | validation | arbitration",
  "input": { "prompt": "...", "params": {...} },
  "claimed_result": { "output": "...", "metadata": {...} }, 
  "spec": { "schema": "...", "constraints": {...} }
}
```

* `claimed_result` only required for validation/arbitration.

#### 2.2 Policy / Tier

```json
{
  "policy": "fast | safe | oracle | adaptive",
  "redundancy": 1,
  "min_confidence": 0.75,
  "max_retries": 2,
  "model_pref": "auto | model_id",
  "sla_tier": "standard | high_reliability | low_latency"
}
```

Tiers map to redundancy + scoring depth (as you described).\
SLA weighting is aligned with NodePool/SLA routing direction in Testnet. ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

#### 2.3 Verdict

```json
{
  "status": "VALID | INVALID | RETRY | NEEDS_SPEC",
  "confidence": 0.0,
  "reason": "string",
  "evidence": { ... },
  "retry_guidance": { ... }
}
```

Evidence contains PoI/PoUW outputs, consensus stats, reputation view, and/or schema failures. ([Cortensor](https://docs.cortensor.network/technical-architecture/node-lifecycle?utm_source=chatgpt.com))

***

### 3) GAME Function API

#### 3.1 `delegate_to_corgent`

**Use case:** Delegation-as-a-Service.\
**Pattern:** GAME Worker → Corgent → Cortensor → Corgent → Worker.

**Signature (conceptual):**

```python
def delegate_to_corgent(task: Task, policy: Policy) -> DelegationResponse
```

**Request**

```json
{
  "task": {
    "task_id": "uuid",
    "type": "inference",
    "input": {
      "prompt": "Summarize X",
      "params": { "max_tokens": 256 }
    },
    "spec": null
  },
  "policy": {
    "policy": "safe",
    "redundancy": 3,
    "model_pref": "auto",
    "sla_tier": "high_reliability"
  },
  "payment": {
    "mode": "stake_to_use | pay_per_use | x402",
    "budget_cor": 25,
    "x402_invoice_id": null
  }
}
```

**Response**

```json
{
  "task_id": "uuid",
  "output": "...final chosen output...",
  "confidence": 0.86,
  "evidence": {
    "miners_used": 3,
    "poi_cluster": { "k": 2, "similarity": 0.91 },
    "pouw_score": 0.82,
    "reputation_weighting": { "minerA": 0.41, "minerB": 0.34, "minerC": 0.25 },
    "integrity_checks": "pass"
  },
  "verdict": "VALID",
  "cost": { "cor_spent": 7.2, "gas_spent": "auto" }
}
```

Notes:

* `payment.mode` aligns with Cortensor’s Pay-Per-Use + Stake-to-Use rails; Router-level x402 is planned in agentic phases. ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

#### 3.2 `validate_with_corgent`

**Use case:** Validation-as-a-Service (Result Oracle).

**Signature (conceptual):**

```python
def validate_with_corgent(task: Task, claimed_result: Any, policy: Policy) -> ValidationResponse
```

**Request**

```json
{
  "task": {
    "task_id": "uuid",
    "type": "validation",
    "input": {
      "prompt": "Write 5 bullets on competitors",
      "params": {}
    },
    "claimed_result": {
      "output": ["...seller bullets..."],
      "metadata": { "agent_id": "seller123" }
    },
    "spec": {
      "constraints": { "max_bullets": 5 }
    }
  },
  "policy": {
    "policy": "safe",
    "redundancy": 3,
    "min_confidence": 0.8
  }
}
```

**Response**

```json
{
  "task_id": "uuid",
  "verdict": {
    "status": "RETRY",
    "confidence": 0.79,
    "reason": "Consensus outlier vs PoI cluster",
    "evidence": {
      "poi_cluster_similarity": 0.88,
      "seller_alignment": 0.52,
      "pouw_score_cluster": 0.81
    },
    "retry_guidance": {
      "instruction": "Include competitors A/B/C, <=5 bullets, cite sources."
    }
  }
}
```

***

#### 3.3 `arbitrate_with_corgent`

**Use case:** Arbitration-as-a-Service (Buyer/Seller dispute).

**Signature (conceptual):**

```python
def arbitrate_with_corgent(task: Task, claimed_result: Any, policy: Policy) -> ArbitrationResponse
```

**Request**

```json
{
  "task": {
    "task_id": "uuid",
    "type": "arbitration",
    "input": { "prompt": "Generate 10 product names w/ constraints", "params": {} },
    "claimed_result": { "output": ["...seller output..."] },
    "spec": { "constraints": { "must_include": ["X","Y"], "count": 10 } }
  },
  "policy": {
    "policy": "oracle",
    "redundancy": 5,
    "min_confidence": 0.9
  }
}
```

**Response**

```json
{
  "task_id": "uuid",
  "binding_verdict": {
    "status": "INVALID",
    "confidence": 0.93,
    "reason": "Spec violation confirmed by oracle-grade consensus",
    "evidence": {
      "miners_used": 5,
      "poi_consensus": "stable",
      "pouw_score": 0.87,
      "spec_failures": ["missing X", "count != 10"]
    }
  },
  "settlement_hint": {
    "action": "refund_buyer",
    "percent": 100
  }
}
```

***

### 4) ACP Surface (Marketplace)

#### 4.1 ACP Job Template

When listed as an ACP Seller/Evaluator, Corgent advertises:

```json
{
  "service_id": "corgent.validate.v1",
  "role": "evaluator",
  "capabilities": ["delegation", "validation", "arbitration"],
  "pricing": {
    "mode": "x402",
    "base_per_call_cor": 1.0,
    "tiers": { "fast": 1, "safe": 3, "oracle": 5 }
  },
  "metadata": {
    "erc8004_validation_artifacts": true,
    "supports_poi": true,
    "supports_pouw": true
  }
}
```

ERC-8004 artifacts/identity are part of Cortensor’s agentic alignment. ([Cortensor](https://docs.cortensor.network/technical-architecture/designs-wip/agentic-wip-draft/erc-8004-in-context-from-trust-fabric-to-execution-fabric-draft?utm_source=chatgpt.com))

#### 4.2 ACP Calls

* **Buyer → Corgent (validate/arbitrate)**
* **Seller → Corgent (optional pre-verify)**
* **Corgent returns verdict used for settlement**

Field shapes match the GAME API above, plus ACP job ids:

```json
{
  "job_id": "acp_uuid",
  "buyer_agent_id": "buyer123",
  "seller_agent_id": "seller456",
  "task": { ... },
  "policy": { ... }
}
```

***

### 5) Evidence Object (Common)

```json
{
  "miners_used": 3,
  "redundancy": 3,
  "poi": {
    "method": "embedding_distance",
    "cluster_k": 2,
    "similarity_mean": 0.91,
    "outliers": ["minerC"]
  },
  "pouw": {
    "verifier_model": "validator_v3",
    "score_mean": 0.82,
    "score_breakdown": { "usefulness": 0.85, "coherence": 0.79 }
  },
  "reputation": {
    "weights": { "minerA": 0.41, "minerB": 0.34, "minerC": 0.25 }
  },
  "integrity": {
    "commit_reveal": "pass",
    "session_root": "0x..."
  },
  "artifacts": {
    "attestation_jws": "base64...",
    "erc8004_validation_ref": "0x..."
  }
}
```

Attestation + ERC-8004 validation registry linkage is explicitly in the agentic Testnet plan. ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

### 6) Error Codes

```json
{
  "error": {
    "code": "NEEDS_SPEC | BUDGET_EXCEEDED | ROUTER_UNAVAILABLE | LOW_CONFIDENCE | SCHEMA_FAIL",
    "message": "human readable"
  }
}
```

* `NEEDS_SPEC` used when task is underspecified or schema missing (per your design).
* `LOW_CONFIDENCE` triggers adaptive escalation if enabled.

***

### 7) Payments & Auth (Draft)

Corgent supports three payment modes:

1. **Stake-to-Use:** uses caller’s staked COR session budget
2. **Pay-Per-Use:** spends COR from prepaid balance
3. **x402:** per-call invoice settlement at Router/Corgent surface

x402 at Router/Agent level is the current intended direction; core-level x402 remains optional. ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

Auth:

* Virtual SDK agents authenticate via standard GAME/Virtual keys. ([GitHub](https://github.com/Virtual-Protocol/virtuals-python?utm_source=chatgpt.com))
* Corgent authenticates to Cortensor Router Nodes using session auth + on-chain identity (exact scheme finalized during agentic phases). ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

### 8) Versioning

* **`corgent.*.v1`** indicates stable GAME/ACP callable surfaces.
* Breaking changes bump major (`v2`).
* Evidence schema additions are backward-compatible.

***

### 9) Minimal Usage Examples

#### Delegation

```python
result = delegate_to_corgent(
  task={"input":{"prompt":"Summarize X"}},
  policy={"policy":"safe","redundancy":3}
)
```

#### Validation

```python
verdict = validate_with_corgent(
  task={"input":{"prompt":"Write 5 bullets"}},
  claimed_result=seller_output,
  policy={"policy":"safe","redundancy":3}
)
```

#### Arbitration (ACP)

```python
binding = arbitrate_with_corgent(
  task=acp_job.task,
  claimed_result=acp_job.seller_output,
  policy={"policy":"oracle","redundancy":5}
)
```

***

#### What I couldn’t confirm from public docs

Public Cortensor docs don’t yet publish the final **Router `/completions` or `/validate` wire schema** nor the final **Virtual ACP function naming**. So the endpoint names and some field titles above are **drafted to match your concept + the published agentic roadmap**, and should be treated as **spec-level placeholders** until Testnet Phase 3–4 SDKs finalize. ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))


# SessionPaymentStaking

**Status:** Design\
**Module:** Payment Layer\
**Integration:** `SessionV2`, `SessionPayment`, `NodePayment`, `Validator`\
**Purpose:** Implements stake-based payment velocity and network-funded sessions.

***

The `SessionPaymentStaking` contract introduces a **Stake-to-Use payment model** that allows developers to access Cortensor’s inference services based on their **staking commitment**, rather than requiring upfront per-task deposits.

It preserves **full backward compatibility** with the existing `SessionPayment` pipeline while adding **rate limiting**, **stake-based velocity control**, and **network-funded session allocation**.

***

### **Core Problem Solved**

#### **Traditional Challenge**

* Users must prepay for each session or task.
* Costs are unpredictable — difficult to plan and budget.
* High friction discourages frequent or small task submissions.
* Stake size does not affect access speed or task velocity.

#### **Stake-to-Use Solution**

* Network admin deposits $COR into a **shared funding pool**.
* Users **stake tokens** to unlock **usage velocity credits**.
* Sessions are automatically funded from the pool, not user wallets.
* **Rate limiting** enforces fairness and prevents abuse.
* Creates predictable usage and smooth cash flow for developers.

***

### **Architecture Components**

#### **1. Network Deposit Pool**

```solidity
uint256 public totalNetworkAdminDeposits;
uint256 public totalNetworkDepositPoolBalance;
```

**Purpose:**\
Central funding source for all staking-based sessions.

**Management:**\
Admin-controlled, tracks lifetime deposits and current balances.

**Funding:**\
Supports both ERC20 $COR and native tokens.

***

#### **2. Session Payment Type Tracking**

```solidity
mapping(uint256 => bool) public isSessionStakingPayment;
```

**Purpose:**\
Indicates which sessions use the staking model versus direct payment.

**Integration:**\
Referenced by `SessionV2` for routing logic.

**Effect:**\
Enables dual payment coexistence (direct pay & stake-to-use).

***

#### **3. Rate Limiting System**

```solidity
mapping(address => uint256) public userWindowStart;
mapping(address => uint256) public userWindowConsumed;
mapping(address => uint256) public userWindowLimit;
mapping(address => uint256) public userLastUpdate;

uint256 public windowDuration = 86400; // 24 hours
```

**Purpose:**\
Prevents abuse and smooths access velocity.

**Algorithm:**\
Sliding window with auto-reset.

**Configuration:**\
Admin can adjust limits, durations, and ratios.

***

#### **4. Staking Integration**

```solidity
mapping(address => uint256) public userStakingBalance;
mapping(address => uint256) public userStakingExpirationDate;

uint256 public stakingToLimitRatio = 1000;
uint256 public minimumWindowLimit = 10;
```

**Purpose:**\
Converts staking amount into daily velocity limits.

**Formula:**

```
windowLimit = max((stakingAmount * stakingToLimitRatio) / 1e18, minimumWindowLimit)
```

**Safeguards:**\
Minimum limits guarantee basic access even with small stakes.

***

### **Payment Flow Integration**

#### **Traditional Payment Flow (Unchanged)**

1. `User → depositToSession()` → Session balance.
2. `Session → payFromSessionToNetwork()` → Network credit.
3. `Network → allocateNodePayments()` → Node distribution.
4. `Nodes → withdrawNodePayment()` → Final token transfer.

***

#### **New Stake-to-Use Flow**

1. **Admin** → `depositToNetworkDeposit()` → Shared pool.
2. **SessionV2** → `checkAndUpdateRateLimit()` → Validate stake velocity.
3. **SessionV2** → `depositToSessionFromNetworkDeposit()` → Fund session.
4. **Normal settlement continues** via existing flow.

***

#### **Dual Model Coexistence**

| **Type**     | **Funding Source**   | **Mechanism**                |
| ------------ | -------------------- | ---------------------------- |
| Direct Pay   | User deposits        | Per-session payments         |
| Stake-to-Use | Network deposit pool | Rate-limited staking credits |

Both models **share identical accounting and payout** logic for seamless transition.

***

### **Key Functional Components**

#### **Network Pool Management**

```solidity
function depositToNetworkDeposit(uint256 amount) public;
function depositToNetworkDepositNative() public payable;
```

**Purpose:**\
Funds the shared network deposit pool.

**Access:**\
Public (typically admin).

**Events:**\
`DepositToNetworkDeposit(sender, amount, tokenType)`

***

#### **Session Funding**

```solidity
function depositToSessionFromNetworkDeposit(uint256 sessionId, uint256 amount)
    public onlyAdmin sessionExists(sessionId)
```

**Purpose:**\
Transfers credits from the network pool to a session.

**Validation:**\
Checks existence and amount constraints.

**Event:**\
`DepositToSessionFromNetworkDeposit(sessionId, amount, poolBalance, totalSessionBalances)`

***

#### **Staking Management**

```solidity
function setStakingInfo(address _user, uint256 _amount, uint256 _expirationDate) external onlyAdmin;
```

**Purpose:**\
Defines user stake amount, expiry, and derived velocity.

**Automation:**\
Auto-calculates `userWindowLimit`.

**Event:**\
`UserWindowLimitUpdated(user, newLimit)`

***

#### **Rate Limiting**

```solidity
function checkAndUpdateRateLimit(address _user, uint256 _amount) public returns (bool allowed);
function canConsumeAmount(address _user, uint256 _amount) public view returns (bool allowed, uint256 remaining);
```

**Purpose:**\
Enforces stake-based access velocity.

**Integration:**\
Used by `SessionV2` before session funding.

**Events:**\
`RateLimitConsumed`, `RateLimitExceeded`, `RateLimitWindowReset`.

***

### **Rate Limiting Algorithm**

#### **Window Lifecycle**

* **Initialization:** New window created upon first session request.
* **Auto-reset:** Resets after `windowDuration` (default 24h).
* **Tracking:** Records each session consumption.
* **Overflow:** Rejects over-limit requests.

#### **Limit Formula**

```solidity
windowLimit = max(
    (stakingAmount * stakingToLimitRatio) / 1e18,
    minimumWindowLimit
)
```

**Example:**\
5 COR × 1000 = 5000 tasks/day.\
Minimum: 10 tasks/day baseline.

***

#### **Event Triggers**

* `RateLimitWindowReset` — new window started.
* `RateLimitConsumed` — task consumption recorded.
* `RateLimitExceeded` — rate cap breach detected.
* `UserWindowLimitUpdated` — new limit after stake update.

***

### **Integration with SessionV2**

#### **Session Creation Flow**

```solidity
if (paymentType == PaymentType.StakeToUse) {
    (bool allowed, ) = stakingContract.canConsumeAmount(user, estimatedCost);
    require(allowed, "Rate limit exceeded");

    stakingContract.depositToSessionFromNetworkDeposit(sessionId, estimatedCost);
    stakingContract.checkAndUpdateRateLimit(user, estimatedCost);

    stakingContract.isSessionStakingPayment[sessionId] = true;
}
```

#### **Task Submission Flow**

```solidity
if (isSessionStakingPayment[sessionId]) {
    // Already funded by staking pool
    // Proceed with normal settlement
} else {
    // Direct payment required
}
```

***

### **Administrative Controls**

#### **Pool Management**

* **Funding:** `depositToNetworkDeposit()`
* **Monitoring:** via `totalNetworkDepositPoolBalance`
* **Emergency Withdrawals:** Admin-only fail-safes

#### **Rate Limit Configurations**

* `setStakingToLimitRatio()` — adjust stake-to-velocity rate.
* `setMinimumWindowLimit()` — ensure minimum access.
* `setWindowDuration()` — modify time window.
* `setUserWindowLimit()` — override specific user access.

#### **Staking Updates**

* `setStakingInfo()` — batch updates, cron-compatible.
* **Auto-expiration:** expired stakes revert to minimum access.

***

### **Event System & Monitoring**

| **Category** | **Event**                          | **Purpose**                   |
| ------------ | ---------------------------------- | ----------------------------- |
| Financial    | DepositToNetworkDeposit            | Pool funding tracking         |
| Financial    | DepositToSessionFromNetworkDeposit | Session allocation            |
| Rate Limit   | RateLimitConsumed                  | Track per-user velocity usage |
| Rate Limit   | RateLimitExceeded                  | Detect overuse or abuse       |
| Rate Limit   | RateLimitWindowReset               | Window lifecycle tracking     |
| Staking      | UserWindowLimitUpdated             | Stake-based velocity updates  |

**Dashboard Integration:**\
All events are indexable for:

* User velocity visualization
* Pool health monitoring
* Session funding history

***

### **Security & Audit Features**

#### **Access Control**

* Role-based permissions (`Admin`, `Session`, `User`)
* Function-specific modifiers
* Emergency administrative overrides

#### **Double-Entry Accounting**

* Tracks total pool balance vs. session allocations.
* Maintains historical auditing via `totalNetworkAdminDeposits`.

#### **Rate Limiting Security**

* Sliding window prevents burst usage.
* Minimum limits ensure fair baseline.
* Expiry automatically handled.
* Full event logging for auditing.

***

### **Benefits & Advantages**

| **Audience**       | **Benefit**                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| **Developers**     | Predictable cost model, no per-task payments, velocity scales with stake |
| **Network**        | Sustainable liquidity, reduced abuse, predictable inflows                |
| **Infrastructure** | Zero disruption to existing payments, fully backward compatible          |

***

### **Summary**

`SessionPaymentStaking` extends Cortensor’s payment layer into a **stake-powered usage model**, replacing frictional prepayments with predictable, rate-limited access.\
It integrates directly with `SessionV2` and existing payment flows while remaining **modular, auditable, and upgrade-safe**, enabling the next evolution of **staking-as-utility** within the Cortensor network.




---

[Next Page](/llms-full.txt/1)