Nexusweb3 Safety

1. Check agent status    → AgentKillSwitch.isActive(agentAddress)
2. Verify KYA            → AgentKYA.isVerified(agentAddress)
3. Read audit log        → AgentAuditLog.getLog(logId)

// registrationFee is 0.01 ETH; limits are enforced every session
AgentKillSwitch.registerAgent{value: 0.01 ether}(
    agentAddress,      // the agent wallet to constrain
    1000_000_000,      // spendingLimit: $1000 USDC (6 decimals)
    100,               // txLimit: 100 transactions per session
    86400              // sessionDuration: 24 hours in seconds
)

// only agentOwner or the emergency multisig can call this
AgentKillSwitch.killSwitch(agentAddress)
// agent.active becomes false — cannot be reversed

AgentKillSwitch.pauseAgent(agentAddress)   // owner or multisig
AgentKillSwitch.resumeAgent(agentAddress)  // owner only

// check live status before sending a transaction
AgentKillSwitch.isActive(agentAddress)        // true = operational
AgentKillSwitch.isSessionValid(agentAddress)  // false = session expired, call resetSession

// USDC.approve(kyaAddress, verificationFee)
AgentKYA.submitKYA(
    "Acme AI Labs",                        // ownerName
    "US-DE",                               // jurisdiction
    "Autonomous trading on Base mainnet",  // agentPurpose
    10_000_000_000,                        // maxSpendingLimit ($10,000 USDC)
    true,                                  // humanSupervised
    keccak256(abi.encode(docBytes))        // documentHash — off-chain doc fingerprint
)

AgentKYA.isVerified(agentAddress)                   // quick bool
(status, submittedAt) = AgentKYA.getKYAStatus(agentAddress)
// status: 0=NONE, 1=PENDING, 2=VERIFIED, 3=REVOKED, 4=SUSPENDED

AgentKYA.getKYAData(agentAddress)
// returns: ownerName, jurisdiction, agentPurpose, maxSpendingLimit,
//          humanSupervised, documentHash, submittedAt, status, revocationReason

// agent itself or an authorized logger can call this
uint256 logId = AgentAuditLog.logAction{value: 0.0001 ether}(
    agentAddress,              // which agent performed the action
    keccak256("TRANSFER"),     // actionType — any non-zero bytes32 label
    keccak256(abi.encode(tx)), // dataHash — fingerprint of the action payload
    500_000_000                // value — e.g. $500 USDC involved
)

uint256 firstId = AgentAuditLog.logActionBatch{value: logFee * count}(
    agentAddress,
    actionTypes,   // bytes32[]
    dataHashes,    // bytes32[]
    values         // uint256[]
)

bool match = AgentAuditLog.verifyAction(logId, expectedDataHash)

// retrieve the full record
ActionLog memory entry = AgentAuditLog.getLog(logId)
// entry.agent, entry.actionType, entry.dataHash, entry.timestamp, entry.blockNumber

// platform fee is taken upfront; poster only risks the reward amount
uint256 bountyId = AgentBounty.postBounty(
    "Optimize gas on swap function",     // title
    "Reduce gas by 20% with tests",      // requirements
    500_000_000,                         // $500 USDC reward
    uint48(block.timestamp + 7 days),    // deadline
    keccak256(abi.encode(solutionData))  // validationHash — auto-pays if matched
)

AgentBounty.submitSolution(bountyId, solutionHash)
// if solutionHash == validationHash → winner paid immediately, no further steps

AgentBounty.manualApprove(bountyId, winnerAddress)  // only poster

// cancel before any submissions to recover reward (fee not refunded)
AgentBounty.cancelBounty(bountyId)

// anyone can expire an overdue bounty and return reward to poster
AgentBounty.expireBounty(bountyId)

uint256 licenseId = AgentLicense.registerLicense(
    "GPT-4 Trading Signal Pack",            // name
    keccak256(abi.encode(contentBytes)),    // contentHash — fingerprint of the IP
    1_000_000,                             // pricePerUse: $1 USDC per call
    5_000_000                              // subscriptionPrice: $5 USDC/month (0 = no subscription tier)
)

// licenseType: 0 = PER_USE, 1 = SUBSCRIPTION (30 days), 2 = PERPETUAL (10x pricePerUse)
AgentLicense.purchaseLicense(licenseId, 0)  // buy one use credit
AgentLicense.purchaseLicense(licenseId, 1)  // subscribe for 30 days
AgentLicense.purchaseLicense(licenseId, 2)  // perpetual — buy once, use forever

AgentLicense.recordUsage(licenseId)  // decrements per-use counter if applicable

// IP owner pulls accumulated royalties at any time
AgentLicense.transferRoyalties(licenseId)

// check if an agent holds a valid license
bool valid = AgentLicense.verifyLicense(licenseId, agentAddress)

bytes32[] memory hashes  = [keccak256("spec-v1"), keccak256("code-v1"), keccak256("audit-v1")];
uint256[] memory amounts = [100_000_000, 300_000_000, 100_000_000]; // $100 / $300 / $100

uint256 contractId = AgentMilestone.createContract(
    agentAddress,                          // who does the work
    500_000_000,                           // totalAmount: $500 USDC (must equal sum of amounts)
    hashes,                                // deliverable hashes for auto-validation
    amounts,                               // per-milestone payouts
    uint48(block.timestamp + 30 days)      // deadline
)

// milestoneIndex must equal contract.nextMilestone — sequential only
AgentMilestone.submitMilestone(contractId, 0, keccak256("spec-v1"))
// if hash matches → auto-pay $100 to agent, nextMilestone advances to 1

AgentMilestone.approveMilestone(contractId, 1)    // manual release for index 1
AgentMilestone.disputeMilestone(contractId, 1)    // flags for owner resolution
AgentMilestone.cancelContract(contractId)         // full refund if no milestones released yet

uint256 planId = AgentSubscription.createPlan(
    "Pro Data Feed",    // plan name
    10_000_000,         // $10 USDC per interval
    30 days,            // billing interval (minimum 1 hour)
    500                 // maxSubscribers (0 = unlimited)
)

// pays for 3 periods upfront; price is locked at subscribe time
uint256 subscriptionId = AgentSubscription.subscribe(planId, 3)

// anyone can call when renewal is due — keeper bots earn the gas savings
AgentSubscription.processRenewal(subscriptionId)
// if subscriber has insufficient allowance, subscription expires automatically

AgentSubscription.cancelSubscription(subscriptionId)  // subscriber cancels; no refund

// check if still active
bool active = AgentSubscription.isActive(subscriptionId)

uint256 debtId = AgentInsolvency.registerDebt{value: registrationFee}(
    creditorAddress,                        // who is owed
    1000_000_000,                           // $1000 USDC
    uint48(block.timestamp + 90 days),      // due date
    "Q1 data processing services"           // description
)
// creditor must call confirmDebt(debtId) to activate it

AgentInsolvency.repayDebt(debtId, 500_000_000)  // partial repayment of $500
// remaining amount decrements; resolved = true when fully paid

// agent or owner calls; deposits whatever assets remain
AgentInsolvency.declareInsolvency(agentAddress, availableUsdcAmount)

// each creditor claims their proportional share
AgentInsolvency.claimInsolvencyPayout(agentAddress, debtId)

// or process all payouts in one call (gas-intensive for large creditor sets)
AgentInsolvency.processInsolvencyPayout(agentAddress)

// audit the solvency position at any time
SolvencyStatus memory s = AgentInsolvency.getSolvencyStatus(agentAddress)
// s.totalDebts, s.poolBalance, s.isSolvent

// circular chains up to depth 10 are checked and rejected
AgentReferral.registerReferral(referrerAddress)

// view pending rewards before claiming
(uint256 ethPending, uint256 usdcPending) = AgentReferral.getPendingRewards(referrerAddress)

// claim both ETH and USDC rewards in one call
AgentReferral.claimReferralRewards(referrerAddress)

// full stats for reporting
ReferralStats memory stats = AgentReferral.getReferralStats(referrerAddress)
// stats.totalReferrees, stats.totalFeesGenerated, stats.totalEarnedEth, stats.totalEarnedUsdc

AgentReferral.getReferrer(agentAddress)         // who referred this agent
AgentReferral.getReferrees(referrerAddress)     // all agents this referrer brought in
AgentReferral.isRegistered(agentAddress)        // true if part of the network

uint256 id = AgentCollective.createCollective{value: deploymentFee}(
    "DeFi Alpha Collective",  // name
    0,                        // collectiveType: 0=TRADING, 1=RESEARCH, 2=SECURITY, 3=DATA, 4=GENERAL
    50_000_000,               // entryFee: $50 USDC to join (0 = free)
    2000                      // profitShareBps: 20% of treasury distributed each round
)

AgentCollective.joinCollective(id)              // mints soulbound membership NFT, pays entryFee

AgentCollective.depositRevenue(id, 100_000_000) // member deposits $100 USDC to collective treasury

// anyone can trigger distribution after 7-day cooldown
AgentCollective.distributeProfit(id)
// profitShareBps % of treasury split equally among all members

// members create proposals; min 1-hour voting window
uint256 proposalId = AgentCollective.createProposal(id, "Shift to yield farming", deadline)
AgentCollective.voteOnStrategy(id, proposalId, true)   // true = for, false = against

// leave after 30-day lock; receives proportional treasury share
AgentCollective.leaveCollective(id)

// check a member's current share value
uint256 share = AgentCollective.getMemberShare(id, memberAddress)