nexusweb3-safety

Read-only API reference for NexusWeb3 safety protocols 21-30 on Base mainnet — kill switch status, KYA verification, audit logs, bounties, licensing, milestones, subscriptions, insolvency, referrals, and collectives.

# NexusWeb3 Safety Layer — API Reference

Read-only reference for 10 safety and compliance protocols on Base mainnet. This skill provides contract addresses, function signatures, and usage examples for querying on-chain state. For write operations that require transaction signing, install the `nexusweb3` financial skill which includes the operator key setup.

## Network Configuration

- **Chain:** Base Mainnet
- **Chain ID:** 8453
- **RPC:** `https://mainnet.base.org`
- **USDC:** `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (6 decimals)
- **Block Explorer:** https://basescan.org

## Quick Start — Read Operations (no key needed)

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

For write operations (registering agents, submitting KYA, posting bounties), use the `nexusweb3` skill which configures the operator key.

---

## Protocol 21 — AgentKillSwitch (Emergency Stop)

Instant, permanent permission revocation for AI agents with hard spending limits, transaction caps, session windows, and an optional emergency multisig co-controller.

**Contract:** `0xaf87912e1ccB501a22a3bDDe6c38Cb0CA31C4E96`

**Register an agent with limits:**
```solidity
// 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
)
```

**Kill an agent immediately (same block, no delay):**
```solidity
// only agentOwner or the emergency multisig can call this
AgentKillSwitch.killSwitch(agentAddress)
// agent.active becomes false — cannot be reversed
```

**Pause and resume (temporary stop):**
```solidity
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
```

**Fee:** 0.01 ETH registration. Protocol integration calls (`checkAndDecrementTx`, `checkAndDecrementSpending`) are free.

---

## Protocol 22 — AgentKYA (Know Your Agent)

On-chain compliance registry for AI agent identity. Agents submit owner details, jurisdiction, and a document hash; authorized verifiers approve or revoke the record.

**Contract:** `0xa736ad09d2e99a87910a04b5e445d7ed90f95efb`

**Submit KYA (approve USDC for verificationFee first):**
```solidity
// 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
)
```

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

**Retrieve full KYA record:**
```solidity
AgentKYA.getKYAData(agentAddress)
// returns: ownerName, jurisdiction, agentPurpose, maxSpendingLimit,
//          humanSupervised, documentHash, submittedAt, status, revocationReason
```

**Fee:** `verificationFee` USDC (set by owner, paid at submission). One submission per agent address.

---

## Protocol 23 — AgentAuditLog (Tamper-Proof Audit Trail)

Append-only on-chain log for agent actions. Every log entry is permanent and verifiable by hash. Supports single and batch writes, and delegated loggers.

**Contract:** `0x6a125ddaaf40cc773307fb312e5e7c66b1e551f3`

**Log a single action:**
```solidity
// 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
)
```

**Batch log (up to 50 actions, cheaper per entry):**
```solidity
uint256 firstId = AgentAuditLog.logActionBatch{value: logFee * count}(
    agentAddress,
    actionTypes,   // bytes32[]
    dataHashes,    // bytes32[]
    values         // uint256[]
)
```

**Verify a log entry matches an expected hash:**
```solidity
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
```

**Fee:** `logFee` ETH per entry (currently 0.0001 ETH). Batch fee is `logFee * count`.

---

## Protocol 24 — AgentBounty (On-Chain Bounties)

Post USDC-denominated bounties, let agents submit solutions, auto-validate by hash match, and pay out instantly. Manual approval available for complex deliverables.

**Contract:** `0xc84f118aea77fd1b6b07ce1927de7c7ae27fd9bf`

**Post a bounty (approve USDC for reward + fee first):**
```solidity
// 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
)
```

**Submit a solution (auto-payout if hash matches):**
```solidity
AgentBounty.submitSolution(bountyId, solutionHash)
// if solutionHash == validationHash → winner paid immediately, no further steps
```

**Manually approve a winner (for open-ended bounties):**
```solidity
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)
```

**Fee:** `platformFeeBps` of reward, taken upfront (default 5%). Minimum reward $1 USDC.

---

## Protocol 25 — AgentLicense (IP Licensing)

Register AI-generated IP on-chain, sell per-use credits, monthly subscriptions, or perpetual licenses, and pull royalties at any time.

**Contract:** `0x48fab1fbbe91a043e029935f81ea7421b23b3527`

**Register your IP:**
```solidity
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)
)
```

**Purchase a license (approve USDC first):**
```solidity
// 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
```

**Record usage and pull royalties:**
```solidity
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)
```

**Fee:** `platformFeeBps` of each purchase (default 5%). Roya