Skip to main content

Capabilities and Roles in NuNet

This page provides a detailed explanation of capabilities, organizations, roles, and how they work together in the NuNet network.

Understanding Organizations​

Organizations are governance entities in NuNet's network ontology that define policies, issue roles, and manage access control within the network. They serve as the primary authority for granting capabilities and managing relationships between entities.

What Are Organizations?​

In NuNet's ontology, an organization is a governance entity with its own DID (Decentralized Identifier) and Device Management Service (DMS) context. Organizations:

  • Issue Roles: Grant roles via capability (UCAN) tokens to persons, nodes, and other entities
  • Anchor Capabilities: Anchor those capabilities in the recipient's DMS context
  • Define Policies: Establish rules that govern how networks, persons, and nodes interact
  • Manage Networks: May oversee one or more networks
  • Delegate Permissions: Grant permissions to people or nodes they trust
  • Set Requirements: Define onboarding requirements such as email verification or manual review

Organization Structure​

Organizations operate at the governance layer of NuNet's four-tier ontology:

  1. Network - The root entity that defines the ontology
  2. Organization - Provides governance and policy
  3. Person - Individual users with their own DID and DMS context
  4. Node - Compute resources or execution environments

Organizations can:

  • Control Networks via administrative roles and capability anchoring
  • Own or manage nodes and persons with administrative or other roles
  • Be members of Networks
  • Manage multiple Networks simultaneously

Organization Identity​

Each organization has:

  • DID (Decentralized Identifier): A unique cryptographic identity
  • DMS Context: Its own Device Management Service context for managing capabilities
  • Capability Anchoring: The ability to anchor capabilities in other entities' DMS contexts

Note: A Network and an Organization can share the same DID, effectively blending their properties into a single combined entity. This means an organization can also be a network.

How Organizations Grant Access​

Organizations grant access through a structured process:

  1. Role Definition: Organizations define roles that bundle specific capabilities
  2. Role Assignment: Organizations assign roles to entities (persons, nodes)
  3. Capability Issuance: Organizations issue UCAN tokens containing the capabilities
  4. Capability Anchoring: Capabilities are anchored in the recipient's DMS context
  5. Verification: Actions are verified against anchored capabilities

Choosing an Organization​

The organization you select determines:

  • Available Roles: Which roles and capabilities become available to you
  • Ensembles: Which compute ensembles you can access or deploy
  • Datasets: Which datasets are available for your use
  • Collaboration Options: How you can interact with other members
  • Onboarding Requirements: What verification or approval process you must complete

Organization Management​

Organizations manage their members and resources through:

  • Onboarding Processes: Define how new members join
  • Role Management: Assign, update, or revoke roles
  • Policy Enforcement: Ensure compliance with network rules
  • Resource Allocation: Manage access to ensembles, datasets, and compute resources
  • Network Coordination: Coordinate activities across their networks

Understanding Capabilities​

Capabilities are fine-grained permissions that define what actions an entity can perform within the NuNet network. They are expressed as UCAN (User Controlled Authorization Networks) tokens and specify precise actions using a path-based namespace.

Capability Namespaces​

Capabilities use a hierarchical namespace structure, similar to file paths. Common capability namespaces include:

  • /dms/deployment - Ability to deploy workloads
  • /dms/node/deployment - Ability to deploy to specific nodes
  • /dms/broadcast - Ability to broadcast messages to a network
  • /dms/deployment/request - Ability to request deployments
  • /dms/deployment/bid - Ability to submit bids for deployments
  • /dms/ensemble/<ensemble-id> - Ability to manage specific ensembles

How Capabilities Work​

  1. Issuance: Organizations issue capabilities via UCAN tokens
  2. Anchoring: Capabilities are anchored in each entity's DMS context
  3. Verification: Every action is verified against the anchored capabilities
  4. Delegation: Capabilities can be delegated to other entities (persons, nodes)

This ensures secure, verifiable, and decentralized authorization without relying on centralized access control systems.

Understanding Roles​

Roles bundle together capabilities and define relationships between entities. A role consists of:

  1. A list of capabilities - What actions the role permits
  2. Entity relationship rules - Who can relate to whom, in what cardinality

Roles on the Network​

NuNet participants can assume two main roles, or combine them as a hybrid contributor. Each role comes with specific capabilities and responsibilities.

Compute Provider​

Compute Providers offer their device's computing resources to the network. They receive workloads (allocations) and execute them on behalf of consumers.

Sample Capabilities:

  • /dms/deployment/bid - Submit bids for available deployments

Responsibilities:

  • Maintain sufficient compute resources (8GB+ RAM, 100GB+ storage recommended)
  • Keep devices online and available
  • Execute workloads reliably and securely
  • Report resource availability and utilization

System Requirements:

  • CPU: 2+ cores (4+ recommended)
  • RAM: 8 GB minimum (16 GB recommended)
  • Disk Space: 100 GB minimum (200 GB+ recommended)
  • Network: Stable broadband connection

Use Cases:

  • Monetize idle compute resources
  • Contribute to distributed computing projects
  • Participate in decentralized compute marketplaces

Important for Compute Providers: VirtualBox does not reserve resources for virtual machines. If you're using your host machine for other tasks while providing compute, you may experience resource conflicts. See Resource Conflicts on Compute Provider Machines for best practices and troubleshooting.

Compute Consumer​

Compute Consumers request and schedule workloads on devices made available by Compute Providers. They deploy applications and services across the network.

** Sample Capabilities:**

  • /dms/node/deployment - Deploy to orchestrator nodes

Responsibilities:

  • Define workload requirements and specifications
  • Select appropriate compute providers
  • Monitor and manage deployed workloads
  • Ensure workloads comply with network policies

System Requirements:

  • CPU: 2+ cores
  • RAM: 4 GB minimum
  • Disk Space: 20 GB minimum
  • Network: Stable broadband connection

Use Cases:

  • Deploy distributed applications
  • Run machine learning training jobs
  • Host decentralized services
  • Execute data processing pipelines

Hybrid Contributor​

Hybrid Contributors both provide compute resources and consume compute from the network. They can switch between roles as needed.

Capabilities:

  • All capabilities from Compute Provider role
  • All capabilities from Compute Consumer role
  • /dms/role/switch - Switch between provider and consumer modes

Responsibilities:

  • Balance providing and consuming compute
  • Manage resources for both roles
  • Optimize for cost and performance

System Requirements:

  • CPU: 4+ cores recommended
  • RAM: 8 GB minimum (16 GB recommended for optimal performance)
  • Disk Space: 100 GB minimum
  • Network: High-speed broadband recommended

Role Selection During Onboarding​

When you join an organization, you'll be asked to select your intended role. This selection:

  • Determines which capabilities are requested from the organization
  • Influences the UI options and features available to you
  • Sets default resource allocation preferences
  • Can be changed later (subject to organization policies)

Multiple Roles​

You can combine roles to become a Hybrid Contributor, giving you the capabilities of both Compute Provider and Compute Consumer. This allows you to both provide compute resources and consume compute from the network, switching between roles as needed.

Role Management​

Roles are managed by Organizations through:

  • Role Assignment: Organizations assign roles to entities
  • Capability Anchoring: Capabilities are anchored in each entity's DMS context
  • Role Revocation: Organizations can revoke roles when needed
  • Role Updates: Roles can be updated to add or remove capabilities

Next Steps​