🔌 SOVEREIGN Protocol

// Basic ERC-20 Functions 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) // Sovereignty Functions function sovereigntyLevel() external view returns (uint256) function isCouncilMember(address account) external view returns (bool) function getCouncilMembers() external view returns (address[] memory)

// ERC-20 Functions function transfer(address to, uint256 amount) external returns (bool) function approve(address spender, uint256 amount) external returns (bool) // Governance Functions (Council Only) function increaseSovereignty(uint256 level) external onlyCouncil function addCouncilMember(address member) external onlyOwner function emergencyPause() external onlyCouncil

// Agent Information function getAgent(address agentAddress) external view returns (Agent memory) function getAgentsByType(AgentType agentType) external view returns (address[] memory) function isAuthorizedAgent(address agentAddress) external view returns (bool) // Agent Types enum AgentType { Treasurer, Voice, Guardian, Analyst, Executor } // Agent Management (Owner Only) function addAgent(address agentAddress, AgentType agentType, string calldata description) function removeAgent(address agentAddress) external onlyOwner function suspendAgent(address agentAddress) external onlyOwner

// Royal Decree Structure struct RoyalDecree { uint256 id; address target; // DeFi protocol address uint256 value; // ETH amount bytes data; // Encoded function call string purpose; // Human-readable description address issuedBy; // Agent that issued the decree uint256 timestamp; // When decree was issued bool executed; // Execution status bool successful; // Success status } // Treasury Functions (Authorized Agents Only) function executeRoyalDecree(RoyalDecree calldata decree) external onlyAuthorizedAgent function executeBatchDecrees(RoyalDecree[] calldata decrees) external onlyAuthorizedAgent // Treasury Statistics function getTreasuryBalance() external view returns (uint256) function getSuccessRate() external view returns (uint256) function getRecentDecrees(uint256 count) external view returns (RoyalDecree[] memory)

// Staking Tiers enum StakingTier { Bronze, Silver, Gold, Platinum } // Tier Requirements Bronze: 1,000 SOV minimum (1.0x Rewards) Silver: 10,000 SOV minimum (1.25x Rewards) Gold: 100,000 SOV minimum (1.5x Rewards) Platinum: 1,000,000 SOV minimum (2.0x Rewards) // Staking Functions function stake(uint256 amount) external function withdraw(uint256 amount) external function claimRewards() external // Staking Information function getStakerInfo(address staker) external view returns (StakerInfo memory) function getStakingTier(address staker) external view returns (StakingTier) function getTotalStaked() external view returns (uint256)

// Agent Status Updates { "event": "agent_status_update", "agentId": "treasurer", "status": "active|inactive|error", "timestamp": "2025-09-24T03:15:07.347Z" } // System Metrics { "event": "system_metrics", "metrics": { "totalAgents": 2, "activeAgents": 2, "systemUptime": "1h 23m 45s" } }

{ "decision": "execute|hold|reject", "confidence": 85, "reasoning": "Market conditions favorable for yield farming", "recommendedAction": { "type": "royal_decree", "target": "0x...", "value": "1000000000000000000", "purpose": "Stake in high-yield USDC pool" }, "riskAssessment": { "level": "medium", "factors": ["impermanent_loss", "smart_contract_risk"] } }

// Initialize contracts const web3 = new Web3(window.ethereum); const contracts = { sovToken: new web3.eth.Contract(SOV_ABI, SOV_ADDRESS), treasury: new web3.eth.Contract(TREASURY_ABI, TREASURY_ADDRESS), staking: new web3.eth.Contract(STAKING_ABI, STAKING_ADDRESS), agentController: new web3.eth.Contract(CONTROLLER_ABI, CONTROLLER_ADDRESS) }; // Get protocol statistics async function getProtocolStats() { const totalSupply = await contracts.sovToken.methods.totalSupply().call(); const treasuryBalance = await contracts.treasury.methods.getTreasuryBalance().call(); const totalStaked = await contracts.staking.methods.getTotalStaked().call(); return { totalSupply: web3.utils.fromWei(totalSupply, 'ether'), treasuryBalance: web3.utils.fromWei(treasuryBalance, 'ether'), totalStaked: web3.utils.fromWei(totalStaked, 'ether') }; }

// Connect wallet async function connectWallet() { if (typeof window.ethereum !== 'undefined') { const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' }); return accounts[0]; } else { throw new Error('MetaMask not installed'); } } // Stake tokens async function stakeTokens(amount) { const accounts = await web3.eth.getAccounts(); const amountWei = web3.utils.toWei(amount.toString(), 'ether'); // Approve tokens first await contracts.sovToken.methods.approve(STAKING_ADDRESS, amountWei) .send({ from: accounts[0] }); // Stake tokens return await contracts.staking.methods.stake(amountWei) .send({ from: accounts[0] }); }

{ "success": false, "error": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient SOV balance for staking", "details": { "required": "1000000000000000000", "available": "500000000000000000" } }, "timestamp": "2025-09-24T03:15:07.347Z" }

{ "success": true, "transaction": { "hash": "0x1234...abcd", "blockNumber": 18450123, "gasUsed": "150000", "status": "confirmed" }, "result": { "type": "stake", "amount": "1000", "newTier": "Silver", "estimatedRewards": "120.5" } }

// Initialize SOVEREIGN protocol integration class SovereignProtocol { constructor(web3Provider) { this.web3 = new Web3(web3Provider); this.contracts = {}; this.initialized = false; } async initialize() { // Load contract addresses const deployment = await fetch('/deployments/localhost-deployment.json'); const addresses = await deployment.json(); // Initialize contracts this.contracts = { sovToken: new this.web3.eth.Contract(SOV_ABI, addresses.contracts.SOVToken), treasury: new this.web3.eth.Contract(TREASURY_ABI, addresses.contracts.SovereignTreasury), staking: new this.web3.eth.Contract(STAKING_ABI, addresses.contracts.SovereignStaking), agentController: new this.web3.eth.Contract(CONTROLLER_ABI, addresses.contracts.AgentController) }; this.initialized = true; } async getProtocolOverview() { if (!this.initialized) await this.initialize(); const [totalSupply, treasuryBalance, totalStaked, successRate, agentCount] = await Promise.all([ this.contracts.sovToken.methods.totalSupply().call(), this.contracts.treasury.methods.getTreasuryBalance().call(), this.contracts.staking.methods.getTotalStaked().call(), this.contracts.treasury.methods.getSuccessRate().call(), this.contracts.agentController.methods.getAgentCount().call() ]); return { totalSupply: this.web3.utils.fromWei(totalSupply, 'ether'), treasuryBalance: this.web3.utils.fromWei(treasuryBalance, 'ether'), totalStaked: this.web3.utils.fromWei(totalStaked, 'ether'), treasurySuccessRate: successRate + '%', activeAgents: parseInt(agentCount) }; } } // Usage const sovereign = new SovereignProtocol(window.ethereum); const overview = await sovereign.getProtocolOverview(); console.log('SOVEREIGN Protocol Overview:', overview);