Developer documentation
WebsiteTechnical Discussions

tokenomics

Last updated: 2024-11-07 21:05:08.625044 File source: link on GitLab

tokenomics

Table of Contents

  1. Description

  2. Structure and Organisation

  3. Class Diagram

  4. Functionality

  5. Data Types

  6. Testing

  7. Proposed Functionality/Requirements

  8. References

Specification

Description

This repository contains implementations for managing contracts, proofs, and payments in tokenomics. Initiated within milestone Device Management Service Version 0.5.x, it offers a comprehensive set of interfaces and methods. To implement these functions, we first define key datatypes and interfaces.

Structure and Organisation

Here is quick overview of the contents of this directory:

  • README: Current file which is aimed towards developers who wish to use and modify the package functionality.

  • Contract.go: Defines the main interface for managing and executing contracts within the tokenomics system.

  • Proofs.go: Implements the interface and logic for proof handling within the tokenomics framework.

  • payments.go: Contains the main interface and functions for processing payments in the tokenomics system.

  • tokenomics.go:: Defines the core functionalities and main interface for the tokenomics package, integrating contracts, proofs, and payments.

Subpackages

  • ./specs/: Directory containing package specifications, including package class diagram.

  • ./Sequences/: Contains the sequence diagram for the tokenomics package

Class Diagram

Source File

tokenomics Class Diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/tokenomics"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

Note: the functionality of Tokenomics is being currently developed. See the proposed section for the suggested design of interfaces and methods.

Data Types

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested data types.

Testing

Unit Tests

TBD

Functional Tests

To be determined (TBD).

Proposed Functionality / Requirements

List of issues related to the design of the tokenomics package can be found below. These include proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

Interfaces and Methods:

Proposed Contract Interface

// Contract defines the methods for contract operations
type contract interface {
	NewContract() Contract
	InitiateContractClosure(n1 dms.NodeID, n2 dms.NodeID, bid dms.orchestrator.Bid)
	InitiateContractSettlement(n1 dms.NodeID, n2 dms.NodeID, contractID int, verificationResult dms.orchestrator.JobVerificationResult)
}

NewContract(): Creates new contract InitiateContractClosure: function initializes and closes a contract between two nodes within the system. It follows the sequence:

  1. Creates a new contract instance.

  2. Populates the contract with job ID and payment details extracted from the provided bid.

  3. Signs and notarizes the contract.

  4. Persists the contract in the contract lists of both nodes (n1 and n2) and the central database.

InitiateContractSettlement: function initiates the settlement process for a specified contract between two nodes (n1 and n2). It executes the following steps:

  1. Updates the contract with the provided verification result.

  2. Executes settlement procedures.

  3. Marks the contract as settled.

  4. Notifies both nodes (n1 and n2) about the settlement.

  5. Updates the contract details in the central database.

Proposed Proof Interface


type proofs interface {
	InitiateContractApproval() error
	CreateContractProof() (string, error)
	SaveProof(contractID, proof string) error
	VerifyProof(contractID, proof string) (bool, error)
}

The InitiateContractApproval(): initiates the contract approval process, starting necessary workflows.

The CreateContractProof(): generates a cryptographic proof for a contract, ensuring transaction integrity.

The SaveProof(contractID, proof string) error: stores the contract proof in a simulated database, maintaining audit trails and historical records.

The VerifyProof(contractID, proof string) (bool, error): verifies the authenticity of a contract proof, ensuring its validity before further processing.

Proposed Payment Interface

// Payment defines the operations for managing payments and settlements
type payments interface {
	Deposit(contractID int, payment tokenomics.Payment, pricing tokenomics.PricingMethod) error
	SettleContract(contractID int, verificationResult dms.jobs.JobVerificationResult) error
}

Deposit: manages the deposit logic for payments, distinguishing between direct and escrow methods. It ensures that only valid payment types (fiat or crypto) are accepted for escrow payments. This function is crucial for initiating the payment process based on the specified method and type.

Parameters:

  • contractID (int): Identifier of the contract associated with the payment.

  • payment (Payment): Struct containing details of the payment, including its method (direct or escrow) and payment type (fiat or crypto).

  • pricing (PricingMethod): Defines the method used to determine the pricing for the deposit (not fully implemented in this function).

    SettleContract: manages the settlement process for contracts based on job verification results. It calculates the payment amount based on the job's completion percentage and processes payments either directly or via escrow, depending on the contract's payment method (direct or escrow). It also handles scenarios where job verification fails and ensures appropriate actions such as refunds for escrow payments.

Data types proposed

proposed tokenomics.Contract: Consists of detailed information regarding an agreement between a requestor and a provider within the network. This data type includes the following fields:

// Contract represents the contract details between nodes
type Contract struct {
	ContractID     int //A unique identifier for the contract.
	JobID          int  //The identifier of the job associated with the contract.
	Requestor      string  //The entity requesting the service.
	Provider       string  //  The entity providing the service.
	PaymentDetails tokenomics.Payment  //An instance of the payments.Payment type, detailing the payment arrangements for the contract.
	Signatures     []dms.nodeID     //A slice of dms.nodeID values, representing the digital signatures of involved parties.
	Settled        bool       //A boolean indicating whether the contract has been settled.
	Verification   dms.orchestrator.JobVerificationResult  //An instance of the orchestrator.JobVerificationResult type, containing the result of the job verification process.
	ContractProof  dms.orchestrator.ContractProof    // An instance of the orchestrator.ContractProof type, providing proof of the contract's terms and conditions.

}

tokenomics.Payment: Consists of details related to a payment transaction between a requestor and a provider, specifying the type, channel, currency, pricing method, and timestamp of the transaction.


type Payment struct {
    Requestor      string        // The entity initiating the payment
    Provider       string        // The entity receiving the payment
    Currency       string        // The currency in which the payment is made
    Timestamp      time.Time     // The time when the payment was made
    PaymentType    string        // The type of payment (e.g., escrow, direct)
    PaymentChannel PaymentChannel // The channel through which the payment is processed
    Pricing        PricingMethod  // The method used for pricing the payment
}

type PricingMethod struct {
    `TBD`
}

type PaymentChannel struct {
    `TBD`
}

tokenomics.FixedJobPricing: Consists of information related to the fixed pricing for a job, detailing the cost and platform fee involved.

goCopy code
// FixedJobPricing represents the details for fixed job pricing
type FixedJobPricing struct {
    // Price is the total cost for the fixed job.
    Price int
    // PlatformFee is the fee charged by the platform for the fixed job.
    PlatformFee int
}

tokenomics.PeriodicPricing: Consists of information related to the periodic pricing model, including the cost, period, usage limits, and platform fee.

goCopy code
// PeriodicPricing represents the details for periodic pricing
type PeriodicPricing struct {
    // Price is the cost for the periodic service.
    Price int
    // Period is the duration of the pricing period (e.g., monthly, yearly).
    Period string
    // UsageLimits defines the maximum allowed usage for resources within the pricing period.
    UsageLimits tokenomics.UsageLimits
    // PlatformFee is the fee charged by the platform for the periodic service.
    PlatformFee int
}

tokenomics.UsageLimits: Consists of information regarding the resource usage limits or quotas associated with periodic pricing, specifying the maximum allowable usage for various resources.

goCopy code
// UsageLimits represents the usage limits or quotas for periodic pricing
type UsageLimits struct {
    // MaxCPUHours is the maximum number of CPU hours allowed within the pricing period.
    MaxCPUHours int
    // MaxMemoryUsage is the maximum amount of memory usage allowed within the pricing period.
    MaxMemoryUsage int
    // MaxStorageUsage is the maximum amount of storage usage allowed within the pricing period.
    MaxStorageUsage int
    // MaxNetworkBandwidth is the maximum network bandwidth usage allowed within the pricing period.
    MaxNetworkBandwidth int
}

tokenomics.Authentication: type is designed to handle the authentication details necessary for secure transaction processing within the payment gateway system. This type includes:

  • Encryption: Specifies the encryption method or protocol used to protect the data involved in the authentication process, ensuring that data is transmitted securely and is kept confidential from unauthorized parties.

  • ZKProof: Contains the zero-knowledge proof (ZKProof) which allows the verification of the transaction's authenticity without exposing sensitive information. This proof ensures that the transaction is valid while preserving privacy.

  • OffChain: Represents off-chain data that supports the authentication process. This data includes information not stored directly on the blockchain but is essential for validating and processing transactions securely.

type Authentication struct {
    // encryption: Defines the encryption protocol used to protect data integrity and confidentiality during the authentication process.
    encryption string

    // ZKProof: Contains the zero-knowledge proof that allows verification of the authentication without disclosing sensitive information.
    ZKProof string

    // OffChain: Holds off-chain data that is essential for the authentication process but not stored on the blockchain.
    OffChain OffChainData
}

type OffChainData struct {
    `TBD`
}

References

PrevioustestNexttypes

Last updated