Smart Contracts

Technical documentation for the NOX smart contract architecture.

---

Contract Overview

┌─────────────────────────────────────────────────────────────────────┐
│                    CONTRACT ARCHITECTURE                            │
└─────────────────────────────────────────────────────────────────────┘

    ┌─────────────────────────────────────────────────────────────────┐
    │                         User Wallet                             │
    └──────────────────────────────┬──────────────────────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
           ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
           │  NOX Token  │ │  Staking    │ │  Rewards    │
           │  (ERC-20)   │ │  Contract   │ │  Contract   │
           └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
                  │               │               │
                  └───────────────┼───────────────┘
                                  │
                                  ▼
                         ┌─────────────┐
                         │  Staking    │
                         │   Vault     │
                         │  (32M NOX)  │
                         └─────────────┘

Contract Addresses

Contract	Address	Verified
NOX Token	0x0a26c80Be4E060e688d7C23aDdB92cBb5D2C9eCA	✓
Staking Vault	0xD548558A7e2666D5580125448B446358F5990423	✓
Staking Contract	TBD (deployment pending)	-

---

NOX Token Contract

Overview

• Standard: ERC-20 with EIP-2612 Permit

• Upgradeability: UUPS Proxy Pattern

• Access Control: Role-based (OpenZeppelin)

Interface

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface INOX {
    // ═══════════════════════════════════════════════════════════════
    //                         ERC-20 STANDARD
    // ═══════════════════════════════════════════════════════════════

    function name() external view returns (string memory);
    function symbol() external view returns (string memory);
    function decimals() external view returns (uint8);
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address to, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);

    // ═══════════════════════════════════════════════════════════════
    //                         EIP-2612 PERMIT
    // ═══════════════════════════════════════════════════════════════

    function permit(
        address owner,
        address spender,
        uint256 value,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external;

    function nonces(address owner) external view returns (uint256);
    function DOMAIN_SEPARATOR() external view returns (bytes32);

    // ═══════════════════════════════════════════════════════════════
    //                         EVENTS
    // ═══════════════════════════════════════════════════════════════

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}

Usage Examples

// Using ethers.js

// Transfer tokens
const tx = await noxToken.transfer(recipientAddress, amount);

// Approve staking contract
const tx = await noxToken.approve(stakingContractAddress, amount);

// Gasless approval with permit
const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour
const nonce = await noxToken.nonces(userAddress);

const signature = await signer._signTypedData(
    {
        name: 'NOX',
        version: '1',
        chainId: 1,
        verifyingContract: noxTokenAddress
    },
    {
        Permit: [
            { name: 'owner', type: 'address' },
            { name: 'spender', type: 'address' },
            { name: 'value', type: 'uint256' },
            { name: 'nonce', type: 'uint256' },
            { name: 'deadline', type: 'uint256' }
        ]
    },
    {
        owner: userAddress,
        spender: stakingContractAddress,
        value: amount,
        nonce: nonce,
        deadline: deadline
    }
);

const { v, r, s } = ethers.utils.splitSignature(signature);
await noxToken.permit(userAddress, stakingContractAddress, amount, deadline, v, r, s);

---

Staking Contract

Overview

The staking contract manages:

• Stake deposits and withdrawals

• Tier management

• Reward distribution

• Quality metrics reporting

Interface

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface INONOSStaking {
    // ═══════════════════════════════════════════════════════════════
    //                         STAKING
    // ═══════════════════════════════════════════════════════════════

    /// @notice Deposit NOX tokens to stake
    /// @param amount Amount of NOX to stake
    function stake(uint256 amount) external;

    /// @notice Deposit with permit (gasless approval)
    /// @param amount Amount to stake
    /// @param deadline Permit deadline
    /// @param v Signature v
    /// @param r Signature r
    /// @param s Signature s
    function stakeWithPermit(
        uint256 amount,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external;

    /// @notice Request withdrawal (starts cooldown)
    /// @param amount Amount to withdraw
    function requestWithdrawal(uint256 amount) external;

    /// @notice Complete withdrawal after cooldown
    function completeWithdrawal() external;

    /// @notice Cancel pending withdrawal
    function cancelWithdrawal() external;

    // ═══════════════════════════════════════════════════════════════
    //                         TIERS
    // ═══════════════════════════════════════════════════════════════

    enum Tier { None, Bronze, Silver, Gold, Platinum, Diamond }

    /// @notice Get current tier for an address
    function getTier(address staker) external view returns (Tier);

    /// @notice Get tier multiplier (in basis points, 10000 = 1.0x)
    function getTierMultiplier(Tier tier) external pure returns (uint256);

    /// @notice Get minimum stake for a tier
    function getTierMinimum(Tier tier) external pure returns (uint256);

    // ═══════════════════════════════════════════════════════════════
    //                         REWARDS
    // ═══════════════════════════════════════════════════════════════

    /// @notice Claim pending rewards
    function claimRewards() external;

    /// @notice Get pending rewards for an address
    function pendingRewards(address staker) external view returns (uint256);

    /// @notice Get reward history
    function getRewardHistory(address staker, uint256 limit)
        external view returns (RewardRecord[] memory);

    // ═══════════════════════════════════════════════════════════════
    //                         QUALITY
    // ═══════════════════════════════════════════════════════════════

    /// @notice Report quality metrics for a node (oracle only)
    /// @param node Node address
    /// @param quality Quality score (0-10000 basis points)
    function reportQuality(address node, uint256 quality) external;

    /// @notice Get quality score for a node
    function getQuality(address node) external view returns (uint256);

    // ═══════════════════════════════════════════════════════════════
    //                         VIEW FUNCTIONS
    // ═══════════════════════════════════════════════════════════════

    /// @notice Get stake info for an address
    function getStakeInfo(address staker) external view returns (
        uint256 stakedAmount,
        Tier tier,
        uint256 pendingWithdrawal,
        uint256 withdrawalReadyAt,
        uint256 quality,
        uint256 streak
    );

    /// @notice Get current epoch number
    function currentEpoch() external view returns (uint256);

    /// @notice Get daily emission rate
    function dailyEmission() external view returns (uint256);

    /// @notice Get total staked across all nodes
    function totalStaked() external view returns (uint256);

    // ═══════════════════════════════════════════════════════════════
    //                         EVENTS
    // ═══════════════════════════════════════════════════════════════

    event Staked(address indexed staker, uint256 amount, Tier tier);
    event WithdrawalRequested(address indexed staker, uint256 amount, uint256 readyAt);
    event WithdrawalCompleted(address indexed staker, uint256 amount);
    event WithdrawalCancelled(address indexed staker, uint256 amount);
    event RewardsClaimed(address indexed staker, uint256 amount, uint256 epoch);
    event QualityReported(address indexed node, uint256 quality, uint256 epoch);
    event TierChanged(address indexed staker, Tier oldTier, Tier newTier);
}

struct RewardRecord {
    uint256 epoch;
    uint256 amount;
    uint256 quality;
    uint256 timestamp;
    bool claimed;
}

State Variables

// Tier configuration
mapping(Tier => uint256) public tierMinimums;
// Bronze: 1,000 NOX, Silver: 10,000 NOX, Gold: 50,000 NOX
// Platinum: 200,000 NOX, Diamond: 1,000,000 NOX

mapping(Tier => uint256) public tierMultipliers;
// Bronze: 10000 (1.0x), Silver: 12000 (1.2x), Gold: 15000 (1.5x)
// Platinum: 20000 (2.0x), Diamond: 25000 (2.5x)

// Emission configuration
uint256 public baseEmission = 50_000 * 10**18; // 50,000 NOX/day initial
uint256 public decayRate = 9993; // 0.9993 daily (basis points)
uint256 public floorEmission = 5_000 * 10**18; // 5,000 NOX/day minimum

// Withdrawal configuration
uint256 public withdrawalCooldown = 7 days;

// Staker state
mapping(address => StakerInfo) public stakers;

struct StakerInfo {
    uint256 stakedAmount;
    uint256 pendingWithdrawal;
    uint256 withdrawalReadyAt;
    uint256 lastClaimedEpoch;
    uint256 quality;
    uint256 streak;
}

Usage Examples

// Stake tokens
const tx = await stakingContract.stake(ethers.utils.parseEther("10000"));

// Stake with permit (no separate approval needed)
const deadline = Math.floor(Date.now() / 1000) + 3600;
const signature = await signPermit(amount, deadline); // Helper function
const { v, r, s } = ethers.utils.splitSignature(signature);
await stakingContract.stakeWithPermit(amount, deadline, v, r, s);

// Check stake info
const info = await stakingContract.getStakeInfo(userAddress);
console.log(`Staked: ${ethers.utils.formatEther(info.stakedAmount)} NOX`);
console.log(`Tier: ${['None', 'Bronze', 'Silver', 'Gold', 'Platinum', 'Diamond'][info.tier]}`);

// Claim rewards
const pending = await stakingContract.pendingRewards(userAddress);
if (pending.gt(0)) {
    await stakingContract.claimRewards();
}

// Request withdrawal
await stakingContract.requestWithdrawal(ethers.utils.parseEther("5000"));

// After cooldown period
await stakingContract.completeWithdrawal();

---

Staking Vault

Overview

The vault holds the 32M NOX allocated for staking rewards.

• Purpose: Secure storage of reward tokens

• Access: Only staking contract can withdraw

• Balance: 32,000,000 NOX initial

---

Security

┌─────────────────────────────────────────────────────────────────────┐
│                    VAULT SECURITY                                    │
└─────────────────────────────────────────────────────────────────────┘

    Access Controls:
    ┌─────────────────────────────────────────────────────────────────┐
    │  Role            │ Permissions                                  │
    ├───────────────────┼─────────────────────────────────────────────┤
    │  ADMIN           │ Upgrade contracts, emergency pause           │
    │  STAKING_CONTRACT│ Withdraw rewards for distribution            │
    │  PUBLIC          │ View balance only                            │
    └───────────────────┴─────────────────────────────────────────────┘

    Withdrawal Flow:
    1. User claims rewards via staking contract
    2. Staking contract calculates reward
    3. Staking contract requests from vault
    4. Vault verifies caller is staking contract
    5. Vault transfers NOX to user

---

Deployment Information

Network Details

Parameter	Value
Network	Ethereum Mainnet
Chain ID	1
Block Explorer	etherscan.io

Deployment Transactions

Contract	Deploy Tx	Block
Staking Contract	TBD	TBD

---

Security Considerations

Audit Status

Auditor	Scope	Date	Status
[Auditor]	Full contracts	TBD	Pending

Known Risks

Upgradeability Risk: UUPS proxy allows upgrades; Mitigation: Multi-sig + timelock on upgrades

Oracle Risk: Quality reporting depends on oracle; Mitigation: Decentralized oracle network (planned)

Smart Contract Risk: Bugs could affect funds; Mitigation: Audits, bug bounty, gradual rollout

Emergency Functions

// Emergency pause (admin only)
function pause() external onlyRole(ADMIN_ROLE);
function unpause() external onlyRole(ADMIN_ROLE);

// Emergency withdrawal (governance only, with timelock)
function emergencyWithdraw(address token, uint256 amount)
    external onlyRole(GOVERNANCE_ROLE);

---

Integration Guide

For Wallets

// Add NOX token
const NOX_TOKEN = {
    address: "0x0a26c80Be4E060e688d7C23aDdB92cBb5D2C9eCA",
    symbol: "NOX",
    decimals: 18,
    chainId: 1
};

For DApps

// Contract ABIs (import from npm package)
import { NOX_ABI, STAKING_ABI } from '@nonos/contracts';

// Connect to contracts
const noxToken = new ethers.Contract(NOX_ADDRESS, NOX_ABI, provider);
const staking = new ethers.Contract(STAKING_ADDRESS, STAKING_ABI, provider);

// Read stake info
const info = await staking.getStakeInfo(userAddress);

// Listen for events
staking.on('Staked', (staker, amount, tier) => {
    console.log(`${staker} staked ${amount} at tier ${tier}`);
});

For Block Explorers

Contract verification available on Etherscan with full source code and ABI.

---

Contract Upgrades

Upgrade Process

1. Proposal: Submit upgrade proposal with new implementation

2. Review: 7-day review period

3. Vote: Governance vote (requires quorum)

4. Timelock: 48-hour timelock after approval

5. Execute: Upgrade executed

---

Upgrade History

Version	Date	Changes
1.0.0	01.09.2025	Initial deployment

---