contracts
Last updated: 2025-08-28 01:08:21.930204 File source: link on GitLab
NuNet Contracts and Tokenomics Architecture Specification
Table of Contents
Executive Summary
The NuNet contracts and tokenomics system represents a sophisticated integration of Agoric's Electronic Rights Transfer Protocol (ERTP) with NuNet's object capability model (nuActor system). This architecture enables secure, decentralized economic contracts for compute resource sharing while maintaining compatibility with both off-platform (Solutions-based) and on-platform (P2P) contract execution.
Key Innovation: The system unifies object capabilities (UCAN/nuActor) with economic contracts (Agoric ERTP), creating a secure, capability-based tokenomics layer that can operate with both trusted third parties and blockchain-based execution environments.
Supported Behaviors
There are two basic behaviors supported by this iteration of the contracts package: simple contract management and complex contract management.
Simple Contract Management
The simple contract management workflow provides a streamlined approach for direct bilateral agreements between Service Providers and Compute Providers.
Key Components
Service Provider (SP): Organization that needs computational resources for their applications
Compute Provider (CP): Organization that supplies computational resources
SP/CP Computers: machines belonging to respective organizations
Contract Host (Solution Enabler): Neutral party that stores and validates contracts
Contract Actors with Execution Engine: Runtime components that enforce contract terms
Contract Database: Persistent storage for signed contract objects
Workflow Description
The simple contract management behavior follows this sequential process:
1. Contract Establishment Phase
Offline Agreement: Service Provider and Compute Provider negotiate terms directly outside the system, establishing a bilateral agreement
Contract Signing: Both parties independently sign the contract using the contract package functionality
Contract Storage: The Contract Host stores the signed contract in the Contract Database
Actor Initialization: Contract Actors are initialized to enforce the agreed terms
2. Deployment Request Phase
Deployment Request: A computer from the Service Provider organization requests deployment from the Compute Provider
Contract Validation: The Compute Provider queries Contract Actors to verify a valid signed contract exists
Decision Point:
Valid Contract: Compute Provider accepts and executes the deployment
Invalid/Missing Contract: Deployment request is rejected
Architecture Diagrams


Complex Contract Management with Solution Enabler
⚠️ Note: This behavior is not implemented in the current contract package and represents a future enhancement to the system.
The complex contract management workflow introduces a Solution Enabler as an intermediary that coordinates transparent multi-party contracts between Solution Providers and Compute Providers. This enables sophisticated deployment scenarios where contract verification happens through capability delegation chains.
Key Components
Solution Enabler (SE): Intermediary that creates and manages contracts with both Solution Providers and Compute Providers
Solution Provider (SP): Organization that provides computational solutions and requests deployments
Compute Provider (CP): Organization that supplies computational resources for execution
SP Computer: Machine belonging to the Solution Provider organization that requests deployments
CP Computer: Machine belonging to the Compute Provider organization that executes deployments
Contract Host: Unified backend system with integrated database and Ocaps verifier for contract storage and verification
Contract Actors: Interface layer that manages contract lifecycle and verification requests
Workflow Description
The complex contract management follows this multi-party process:
1. Dual Contract Establishment Phase
SE-to-CP Contract Creation: Solution Enabler creates a contract with the Compute Provider
CP Contract Signing: Compute Provider signs the contract, triggering contract actor creation
SE-to-SP Contract Creation: Solution Enabler creates a separate contract with the Solution Provider
SP Contract Signing: Solution Provider signs the contract, triggering contract actor creation
2. Deployment Request Phase
SP Deployment Request: A computer from the Solution Provider organization requests deployment from the Compute Provider (includes SP-DID)
3. Contract Chain Verification Phase
⚠️ Note: This ocap chain verification functionality is not currently implemented and needs to be developed in order to support this complex contract management behavior.
Contract Chain Query: Compute Provider queries Contract Actors to verify the existence of a complex contract chain
Chain Verification: Contract Actors request verification from the Contract Host, which performs ocap chain verification to:
Find contracts where CP is a party
Find contracts where SP is a party
Check if the same SE is involved in both contracts
Verify transparency properties
Validate capability delegation
4. Deployment Decision Phase
Verification Result: Based on contract chain validity:
Valid Chain: Contract Host confirms valid chain → Contract Actors notify CP → Deployment accepted
Invalid Chain: Contract Host rejects chain → Contract Actors notify CP → Deployment rejected
5. Deployment and Execution Phase
Deployment Execution: If valid, CP Computer accepts deployment and SP Computer executes the job
Completion: SP Computer notifies CP Computer of job completion
Architecture Diagrams


Architecture Overview
System Components Hierarchy
NuNet Platform
├── Device Management Service (DMS)
│ ├── Contract Sub-package
│ │ ├── Contract Objects (nuActors)
│ │ ├── Contract Logic (FSM)
│ │ └── Capability Management
│ ├── Orchestration Layer
│ └── nuActor System Integration
├── Contract Database (CloverDB/External)
└── Contract Host (Trusted Execution Environment)
Core Architecture Diagram
Based on the detailed design from GitLab Issue #371:

Core Design Principles
1. Electronic Rights Transfer Protocol (ERTP) Integration
E-rights: Digital representations of property rights to assets
Contract Objects: Special nuActors that execute contract logic
Issuers: Authorities that validate digital asset rights (we are not daling with them explicitly in our contract logic)
Contract Hosts: Trusted execution environments
2. Object Capability Security Model
All economic interactions mediated through capability grants
Contract parties can only access assets through contract-granted capabilities
Capability delegation ensures secure resource access control
3. Finite State Machine Contract Logic
All contracts modeled as deterministic state machines
Well-defined side effects for input/output operations
Support for both automated logic and dispute resolution mechanisms
(currently only partially implemented as not needed for externally defined contracts to work -- which is the first iteration of contract package implemenation)
4. Blockchain-Agnostic Design
Current implementation uses trusted third parties (NuNet Solutions)
Architecture supports adding blockchain based papyment layers or even migration to blockchain-based execution;
Object capability security maintained across execution environments
Conceptual Framework
Contract Parties and Assets
Contract Parties: Entities that enter into contracts with intention to exchange assets according to contract rules.
Assets: Physical property, computational resources, or services owned by contract parties. In NuNet context:
Compute Resources: DMS-enabled machines, CPU/GPU time, storage
Financial Assets: Payment tokens, coins, escrow funds
Service Rights: Access to specific computational workflows
Key Architectural Entities
Issuer
An authority that validates digital assets of its kind. Can be:
Asset owner (simple cases)
Third-party validation service
Blockchain-based validator Our main usecase does not require explicit definition of issuers (owners of machines have right to delegate access to their compute resources without explicit proof, just by having physical access to a machine). Therefore issues are not defined in current implementation of contract package.
Contract Host
Trusted third party executing contract logic and maintaining records:
Current: NuNet Solutions or trusted solution providers
Future: Blockchain networks with smart contract support
Hybrid: Combination of trusted entities and blockchain validation
Contract Logic
Two-part system:
Pre-defined Behaviors: Algorithmic logic (smart contracts)
Dispute Resolution: Oracle/arbiter mechanisms for non-predefined scenarios Contracts are implemented as nuActors in the system, therefore can have their own execution environments running arbitrary logic.
Contract Chairs
Expression of rights that contract grants to parties. Enables partial asset commitment to contracts.
E-Rights
Proof of property rights to assets bound by contract terms. Enable secure asset transfer based on contract logic execution.
Implementation Architecture
Contract Sub-Package Design
Location: dms/contract
sub-package within Device Management Service
Core Components:
1. Contract Objects as nuActors
DID-anchored: Each contract has unique decentralized identifier
Persistent Execution: Run as special allocation actors with own addresses and mailboxes
Message Dispatch: Direct message handling via nuActor system
Security Isolation: Restricted to trusted contract hosts only
2. Contract Database Integration
Storage: CloverDB (internal) or external document database
Format: Go scripts following well-defined contract templates
Access: Contract hosts pull contracts for execution
Versioning: Support for contract updates and state transitions
3. Capability Management
Issuing: Contract host issues capabilities via nuActor dispatch
Verification: Capability checking for contract execution
Delegation: Contract-based capability grants to parties Follows secure programming
References and Links
Primary Design Documents
Issue #371: Job orchestration design using Contract Database
Main conceptual design with comprehensive PlantUML diagrams
Electronic rights protocol architecture
Detailed contract object specifications
Issue #765: Contract sub-package conceptual design
Implementation guidelines for contract objects as nuActors
Go-based contract patterns and finite state machine execution
Integration with DMS orchestration layer
Issue #699: Review Agoric concepts of Contracts with OCaps
Agoric ERTP integration research
Object capability model unification
Educational resources and implementation insights
Architecture Work Packages
Issue #464: Network Tokenomics Layer
Comprehensive tokenomics implementation plan
P2P contracts based on conceptual design
Smart contracts for escrow, staking, and network incentives
Escrow contract implementation specifications
Staking contract mechanisms
Network incentives smart contracts integration
Implementation Issues
Related Merge Request #1931
Related Resources
Agoric Documentation:
Academic References:
"The Digital Path: Smart Contracts and the Third World" by Mark S. Miller
"Markets and Computation: Agoric Open Systems"
"Distributed Electronic Rights in JavaScript"
"Habitat Chronicles: What Are Capabilities?"
Last updated