# 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 ```protobuf 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: ```json { "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` ```solidity 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` ```solidity 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` ```solidity function handleExpiredRequest(bytes32 requestId) external; ``` **Behavior:** * If request expired, refund to original payer * Anyone can call (gas incentive) ### Events ```solidity 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 ```bash # 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 ```bash # 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 ```javascript // 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](/nc/neurochainai-guides/architecture/validation-consensus.md) - Validator mechanism * [Smart Contracts](/nc/neurochainai-guides/components/smart-contracts.md) - Contract details * [Security Model](/nc/neurochainai-guides/architecture/security-model.md) - Security architecture --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.neurochain.ai/nc/neurochainai-guides/architecture/payment-flow.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.