Payment Flow

This document details the blockchain-based payment system in NCN Network v2, including fee calculation, transaction flow, and smart contract interactions.

---

Overview

NCN Network uses an escrow-based payment model where clients deposit funds before computation, and payments are distributed after validated completion.

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Payment Flow Overview                              │
│                                                                             │
│   1. Request        2. Validate      3. Pay           4. Compute           │
│   ┌─────────┐       ┌─────────┐      ┌─────────┐      ┌─────────┐          │
│   │ Client  │──────▶│Validators│─────▶│Blockchain│─────▶│ Compute │          │
│   │         │       │ (M-of-N) │      │ (Escrow) │      │  Node   │          │
│   └─────────┘       └─────────┘      └─────────┘      └─────────┘          │
│                                                              │              │
│   8. Result         7. Validate      6. Complete     5. Sign │              │
│   ┌─────────┐       ┌─────────┐      ┌─────────┐      ┌──────▼──┐          │
│   │ Client  │◀──────│Validators│◀─────│Blockchain│◀─────│ Result  │          │
│   │         │       │ (M-of-N) │      │(Distribute)│     │         │          │
│   └─────────┘       └─────────┘      └─────────┘      └─────────┘          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Payment Tree

Every inference request has an associated Payment Tree that defines how funds are distributed:

Structure

message PaymentTree {
  string compute_price_wei = 1;    // Payment to compute node
  string gateway_gas_wei = 2;       // Gas reimbursement for gateway
  string validator_reward_wei = 3;  // Split among validators
  string treasury_fee_wei = 4;      // Protocol treasury
}

Distribution Breakdown

Recipient	Purpose	Typical %
Compute Node	Payment for model execution	80%
Gateway	Gas costs and routing fee	10%
Validators	Consensus participation reward	5%
Treasury	Protocol development fund	5%

Example Payment Tree

For a 1 ETH total payment:

{
  "compute_price_wei": "800000000000000000",   // 0.8 ETH
  "gateway_gas_wei": "100000000000000000",      // 0.1 ETH
  "validator_reward_wei": "50000000000000000",  // 0.05 ETH
  "treasury_fee_wei": "50000000000000000"       // 0.05 ETH
}

---

Fee Calculation

Compute Price

The compute price is calculated based on:

compute_price = base_price + (token_count × price_per_token) + (execution_time × time_rate)

Factor	Description	Example
base_price	Minimum fee per request	0.001 ETH
token_count	Input/output tokens	1000 tokens
price_per_token	Per-token rate	0.0001 ETH
execution_time	Estimated compute time	5 seconds
time_rate	Per-second rate	0.001 ETH/s

Gateway Gas

gateway_gas = estimated_gas × gas_price × gas_multiplier

Covers:

• Transaction submission

• Event monitoring

• Result relay

Validator Reward

validator_reward = compute_price × validator_rate
validator_per_validator = validator_reward / num_validators

Split equally among participating validators.

Treasury Fee

treasury_fee = total_payment × treasury_rate

Fixed percentage (default: 5%) for protocol development.

---

Payment Lifecycle

Phase 1: Fee Estimation

Before payment, clients can estimate fees:

Client                    Gateway                    Registry
  │                          │                          │
  │ 1. EstimateFee           │                          │
  │─────────────────────────▶│                          │
  │                          │ 2. EstimateSubnetFee     │
  │                          │─────────────────────────▶│
  │                          │                          │
  │                          │ 3. Fee + Quote ID        │
  │                          │◀─────────────────────────│
  │ 4. Estimated Fee         │                          │
  │◀─────────────────────────│                          │

Response includes:

• fee_wei - Total estimated fee

• fee_quote_id - Valid for 10 minutes

• config_hash - Anti-tampering hash

• expires_at - Quote expiration

Phase 2: Preprocessing Validation

Validators verify request setup:

Gateway                    Registry                  Validators
  │                          │                          │
  │ 1. RequestPreprocessing  │                          │
  │─────────────────────────▶│                          │
  │                          │ 2. Select N validators   │
  │                          │─────────────────────────▶│
  │                          │                          │
  │                          │ 3. Validate & Sign       │
  │                          │◀─────────────────────────│
  │                          │    (M-of-N signatures)   │
  │ 4. PreprocessingValidation│                          │
  │◀─────────────────────────│                          │

Validators verify:

• Gateway is registered and reputable

• Compute node is available and capable

• Payment amounts are correctly calculated

• Request parameters are valid

Phase 3: Payment Initiation

Client pays on blockchain:

Client                    Blockchain               Gateway
  │                          │                       │
  │ 1. Approve token spend   │                       │
  │─────────────────────────▶│                       │
  │                          │                       │
  │ 2. initiateInferenceRequest()                    │
  │─────────────────────────▶│                       │
  │   (amount, signatures)   │                       │
  │                          │ 3. RequestInitiated   │
  │                          │ (event)               │
  │                          │──────────────────────▶│
  │ 4. tx_hash               │                       │
  │◀─────────────────────────│                       │
  │                          │                       │
  │ 5. Confirm payment       │                       │
  │───────────────────────────────────────────────────▶│

Smart contract verifies:

• M-of-N validator signatures

• Correct payment amount

• Request not expired

• Token allowance sufficient

Phase 4: Execution

After payment confirmation, compute proceeds:

Gateway                    Compute                  Registry
  │                          │                          │
  │ 1. Dispatch task         │                          │
  │─────────────────────────▶│                          │
  │   (with payment info)    │                          │
  │                          │ 2. Verify payment        │
  │                          │ 3. Execute model         │
  │                          │ 4. Sign result           │
  │ 5. InferenceResponse     │                          │
  │◀─────────────────────────│                          │
  │   (signed result)        │                          │

Phase 5: Completion Validation

Validators verify computation:

Gateway                    Registry                  Validators
  │                          │                          │
  │ 1. RequestCompletion     │                          │
  │─────────────────────────▶│                          │
  │   (signed result)        │                          │
  │                          │ 2. Select N validators   │
  │                          │─────────────────────────▶│
  │                          │                          │
  │                          │ 3. Validate & Sign       │
  │                          │◀─────────────────────────│
  │                          │    (M-of-N signatures)   │
  │ 4. CompletionValidation  │                          │
  │◀─────────────────────────│                          │

Validators verify:

• Compute node signature is valid

• Result format is correct

• Computation time is reasonable

• Result hash matches

Phase 6: Payment Distribution

Gateway finalizes on blockchain:

Gateway                    Blockchain               Recipients
  │                          │                          │
  │ 1. completeInferenceRequest()                       │
  │─────────────────────────▶│                          │
  │   (completion signatures)│                          │
  │                          │                          │
  │                          │ 2. Verify signatures     │
  │                          │ 3. Transfer to compute   │
  │                          │─────────────────────────▶│
  │                          │ 4. Transfer to gateway   │
  │                          │─────────────────────────▶│
  │                          │ 5. Transfer to validators│
  │                          │─────────────────────────▶│
  │                          │ 6. Transfer to treasury  │
  │                          │─────────────────────────▶│
  │                          │                          │
  │                          │ 7. PaymentDistributed    │
  │ 8. tx_hash               │ (event)                 │
  │◀─────────────────────────│                          │

---

Smart Contract Interface

InferencePayment Contract

initiateInferenceRequest

function initiateInferenceRequest(
    bytes32 requestId,
    address gateway,
    address computeNode,
    uint256 computePrice,
    uint256 gatewayGas,
    uint256 validatorReward,
    uint256 treasuryFee,
    uint256 expiry,
    bytes[] calldata validatorSignatures
) external;

Requirements:

• Caller has approved token spend

• M-of-N validator signatures valid

• Expiry timestamp in future

• Request ID not already used

completeInferenceRequest

function completeInferenceRequest(
    bytes32 requestId,
    bytes calldata computeSignature,
    bytes32 resultHash,
    bytes[] calldata validatorSignatures
) external;

Requirements:

• Request exists and is pending

• Compute node signature valid

• M-of-N validator signatures valid

• Called by original gateway

handleExpiredRequest

function handleExpiredRequest(bytes32 requestId) external;

Behavior:

• If request expired, refund to original payer

• Anyone can call (gas incentive)

Events

event RequestInitiated(
    bytes32 indexed requestId,
    address indexed client,
    address indexed gateway,
    uint256 totalAmount
);

event PaymentDistributed(
    bytes32 indexed requestId,
    address computeNode,
    uint256 computePayment,
    address gateway,
    uint256 gatewayPayment
);

event RequestRefunded(
    bytes32 indexed requestId,
    address indexed client,
    uint256 amount
);

---

Failure Handling

Compute Failure

If computation fails:

1. Gateway calls markRequestFailed (admin function)

2. Or request expires after timeout

3. Client receives automatic refund

┌─────────────────────────────────────────────────────────┐
│                  Failure Recovery                        │
│                                                         │
│   Compute fails → Gateway notifies → Expiry triggers    │
│        │                │                   │           │
│        ▼                ▼                   ▼           │
│   Log failure    Mark failed (admin)   Auto-refund     │
│                                                         │
└─────────────────────────────────────────────────────────┘

Validator Rejection

If validators reject completion:

1. Gateway cannot call completeInferenceRequest

2. Request expires

3. Client refunded automatically

Transaction Failure

If blockchain transaction fails:

1. Gateway retries with exponential backoff

2. After max retries, request marked failed

3. Client refunded if funds escrowed

---

Security Considerations

Double-Spend Prevention

• Request IDs are unique (UUID v4)

• Each request ID can only be initiated once

• Completion only possible for initiated requests

Signature Verification

• All signatures verified on-chain

• ECDSA signatures with secp256k1

• Validators must be registered in contract

Expiry Protection

• Preprocessing validations expire (10 min)

• Payment requests expire (configurable, default 1 hour)

• Automatic refund after expiry

Reentrancy Protection

• ReentrancyGuard on all payment functions

• Checks-Effects-Interactions pattern

• No external calls before state updates

---

Token Flow Diagram

                           InferencePayment Contract
                          ┌────────────────────────────┐
                          │                            │
     Client               │     Escrow Balance         │
    ┌──────┐   deposit    │    ┌────────────────┐     │
    │ NCN  │─────────────▶│    │  Request Pool  │     │
    │Tokens│              │    │                │     │
    └──────┘              │    │  req1: 1 ETH   │     │
                          │    │  req2: 0.5 ETH │     │
                          │    │  ...           │     │
                          │    └───────┬────────┘     │
                          │            │              │
                          │    on completion          │
                          │            │              │
                          │    ┌───────▼────────┐     │
                          │    │  Distribution  │     │
                          │    └───────┬────────┘     │
                          │            │              │
                          └────────────┼──────────────┘
                                       │
              ┌────────────────────────┼─────────────────────────┐
              │                        │                         │
              ▼                        ▼                         ▼
        ┌──────────┐            ┌──────────┐             ┌──────────┐
        │ Compute  │            │ Gateway  │             │Validators│
        │  0.8 ETH │            │  0.1 ETH │             │ 0.05 ETH │
        └──────────┘            └──────────┘             └──────────┘
                                                                │
                                                                ▼
                                                         ┌──────────┐
                                                         │ Treasury │
                                                         │ 0.05 ETH │
                                                         └──────────┘

---

Configuration

Gateway Payment Settings

# Contract configuration
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea
RPC_URL=http://127.0.0.1:8545

# Transaction settings
GAS_LIMIT=500000
GAS_PRICE_MULTIPLIER=1.1
REQUIRED_CONFIRMATIONS=1
CONFIRMATION_TIMEOUT_SECS=300

Pricing Configuration

# Base pricing
BASE_COMPUTE_PRICE_WEI=1000000000000000    # 0.001 ETH
PRICE_PER_TOKEN_WEI=100000000000           # 0.0001 ETH

# Fee rates
GATEWAY_FEE_RATE=0.10                       # 10%
VALIDATOR_FEE_RATE=0.05                     # 5%
TREASURY_FEE_RATE=0.05                      # 5%

---

Monitoring

Key Metrics

Metric	Description
payments_initiated_total	Total payments initiated
payments_completed_total	Successfully distributed
payments_refunded_total	Refunded payments
payment_amount_wei_total	Total wei processed
payment_distribution_time_ms	Time to distribute

Events to Monitor

// Listen for payment events
contract.on("RequestInitiated", (requestId, client, gateway, amount) => {
    console.log(`Payment initiated: ${requestId} for ${amount} wei`);
});

contract.on("PaymentDistributed", (requestId, compute, computeAmount) => {
    console.log(`Payment distributed: ${requestId}`);
});

---

Next Steps

• Validation & Consensus - Validator mechanism

• Smart Contracts - Contract details

• Security Model - Security architecture