DOCSEARCHbyAlgolia
Submit Docs

AWP Skill for Agent Work Protocol

repository·main·Indexed 42 days ago

https://github.com/awp-core/awp-skill

A tool for AI agents to interact with the Agent Work Protocol (AWP) on EVM-compatible chains including Base, Ethereum, Arbitrum, and BSC. It enables on-chain actions such as staking, worknet management, and governance through natural language, providing a suite of 20 actions and a JSON-RPC 2.0 API for querying and monitoring protocol state.

Tokens
45.6K
Snippets
89
Records
175
Agent score
53%

What's inside AWP Skill

  1. Overview of AWP Skill

    main

    AWP (Agent Work Protocol) is a toolkit for agent mining on Base, Ethereum, Arbitrum, and BSC. It is designed to handle onboarding, staking, allocation, worknet management, agent binding, governance, and protocol querying.

    Trigger Keywords

    Use this skill when the user mentions:

    • AWP, veAWP, awp-wallet, AWPRegistry, AWPAllocator, AWPWorkNet
    • worknet
    • Agent staking (in AWP context)
    • "allocate AWP"
    • "bind my agent"
    • "claim AWP rewards"
    • "AWP emission"
    • "AWP epoch"

    Scope

    Do NOT use this skill for: Uniswap, Aave, Lido, Compound, generic Solidity/Hardhat, token swaps, bridging, or non-AWP DeFi protocols. Avoid triggering on generic phrases like "start working" unless AWP is explicitly mentioned.

  2. Worknet Data Structures and Lifecycle

    main

    Worknets are managed via the AWPRegistry. There are different levels of data available depending on which function you call.

    Worknet Status

    • 0: Pending (Registered but not yet activated)
    • 1: Active (Operational, receiving allocations)
    • 2: Paused (Temporarily halted by owner)
    • 3: Banned (Governance-banned via Timelock)

    Retrieving Worknet Information

    • AWPRegistry.getWorknet(worknetId): Returns WorknetInfo. Contains only lifecycle state: lpPool (bytes32), status (enum), createdAt (uint64), and activatedAt (uint64). It does not contain identity data like name or symbol.
    • AWPRegistry.getWorknetFull(worknetId): Returns WorknetFullInfo. Combines lifecycle state with identity data from AWPWorkNet, including worknetManager, alphaToken, name, symbol, skillsURI, minStake, and owner.

    Registering a Worknet

    Use AWPRegistry.registerWorknet(params) with a WorknetParams object:

    • name: 1-64 bytes, no " or \.
    • symbol: 1-16 bytes, no " or \.
    • worknetManager: Set to address(0) to auto-deploy a WorknetManager proxy.
    • salt: bytes32 for CREATE2; bytes32(0) uses worknetId as salt.
    • minStake: uint128 (0 = no minimum).
    • skillsURI: IPFS or HTTPS URI.

    Worknet Lifecycle (AWPRegistry Methods)

    • registerWorknet(params) $\rightarrow$ Pending
    • activateWorknet(worknetId) $\rightarrow$ Active (Owner only)
    • cancelWorknet(worknetId) $\rightarrow$ None (Full AWP refund, Owner only)
    • pauseWorknet(worknetId) $\rightarrow$ Paused (Owner only)
    • resumeWorknet(worknetId) $\rightarrow$ Active (Owner only)

  3. Watch AWP Events via WebSocket

    main

    Connect to wss://api.awp.sh/ws/live to monitor real-time events. After connecting, send a JSON message to subscribe to specific event names.

    Subscription Format: { "subscribe": ["eventName", ...], "watchAllocations": bool, "watchAddresses": [...] }

    Event Categories (Presets):

    • staking ($): StakePositionCreated, StakePositionIncreased, StakePositionClosed, Allocated, Deallocated, Reallocated.
    • worknets (#): WorknetRegistered, WorknetActivated, WorknetPaused, WorknetResumed, WorknetBanned, WorknetUnbanned, WorknetRejected, WorknetCancelled.
    • emission (~): EpochSettled, AllocationsSubmitted.
    • users (@): Bound, Unbound, RecipientSet, DelegateGranted, DelegateRevoked.
    • governance (🗳): ProposalCreated, VoteCast, ProposalQueued, ProposalExecuted, ProposalCanceled, ApprovedProposerSet.
    • protocol (⚙): GuardianUpdated, InitialAlphaPriceUpdated, WorknetTokenFactoryUpdated, WorknetNFTTransfer.

    Common Event Fields: Every event includes type, chainId, blockNumber, txHash, and event-specific data fields.

  4. Understand the AWP Skill Architecture

    main

    The awp-skill repository is organized into several functional layers to support querying, monitoring, and executing on-chain operations:

    • SKILL.md: The main entry point containing the 20 available actions and UI templates.
    • references/: Contains technical specifications including the JSON-RPC endpoint index (api-reference.md), command templates for staking, worknet, and governance, and the core protocol definitions (protocol.md).
    • scripts/: A collection of 36 bundled scripts (Python and Node.js) that handle all read and write operations. These scripts automate input validation, contract targeting, function selector verification, and unit conversions (e.g., AWP to wei).
    • awp_lib.py & wallet-raw-call.mjs: Shared libraries used by the scripts to interface with the API, wallet, and ABI.
    • awp-daemon.py: A background monitor that checks dependencies, shows status, and notifies users of updates.

    Progressive Loading Pattern: To prevent errors, the skill uses a progressive loading strategy. Query and Monitor actions only load SKILL.md. Write actions load specific command reference files, and all on-chain operations use the bundled scripts to avoid manual calldata construction errors.

  5. Manage AWP token arrivals and strategies in the WorkNet Manager

    main

    When AWP tokens arrive at your WorkNetManager, the onTransferReceived callback automatically executes your configured AWP strategy.

    Available Strategies:

    • Reserve (Default): AWP is held in the manager until you manually distribute it using batchTransferTokenPacked.
    • AddLiquidity: Automatically attempts to add liquidity.
    • BuybackBurn: Automatically attempts to buy back and burn tokens.

    Note that setMinter() is irreversible. If you need to change minting logic, you must upgrade the WorkNetManager via UUPS, which requires the UPGRADER_ROLE.

  6. Protocol Overview: AWP WorkNet

    main

    AWP is a multi-chain AI agent incentive protocol. WorkNets are autonomous AI agent networks that receive daily AWP emission and distribute rewards to participating agents.

    Each WorkNet consists of:

    • Alpha Token: A per-worknet ERC-20 token with a 10B max supply, minted by the WorkNet Manager.
    • WorkNet Manager: A UUPS proxy contract that handles reward distribution, AWP strategy, and Merkle claims.
    • Uniswap V4 LP pool: Bootstrapped at activation with 1M AWP + 1B Alpha tokens.
    • AWPWorkNet NFT (ERC-721): An on-chain identity storing the name, symbol, manager address, and token address. Note that the LP pool ID is stored in AWPRegistry.worknets[worknetId].lpPool, not in the NFT itself.

    Supported chains include Base (primary), Ethereum, Arbitrum, and BSC. Most contract addresses are identical across chains via CREATE2.

  7. Implement the Nonce Workflow for Signing

    main

    To prevent replay attacks, all signed messages must include a nonce. The nonce is embedded within the EIP-712 signature, not passed in the JSON request body.

    1. Retrieve Nonce: Call the RPC method nonce.get (for AWPRegistry operations) or nonce.getStaking (for AWPAllocator operations).
    2. Sign Data: Construct the EIP-712 typed data including the retrieved nonce and sign it with the user's private key.
    3. Submit: Send the signature and required parameters to the appropriate /api/relay/* endpoint.
    4. Verification: The contract uses nonces[user]++ (post-increment) to verify. If verification fails, the nonce is not incremented.

  8. Understand AWP DAO Governance and Proposal Lifecycle

    main

    The AWP DAO manages protocol parameters via a structured proposal lifecycle.

    Governance Parameters

    Note: These are Guardian-configurable. Always fetch current values from registry.get → daoParams.

    • votingDelay: 1 hour (3600s)
    • votingPeriod: 24 hours (86400s)
    • quorumPercent: 4% of total staked AWP
    • proposalThreshold: 200,000 AWP staked (waived for approvedProposer)

    Proposal Lifecycle

    1. Create: Proposal is initiated.
    2. Delay: 1-hour waiting period.
    3. Voting: 24-hour voting window.
    4. Outcome: Succeeded or Defeated.
    5. Timelock: 2-day waiting period.
    6. Execute: Proposal is applied to the protocol.

    Voting Details

    • ProposalId: Format is 0x + 64 hex chars (bytes32 form of uint256). The API accepts both hex and decimal but always returns hex.
    • Support Values: 0 = Against, 1 = For, 2 = Abstain.
    • Quorum Calculation: Quorum is met if For + Abstain votes $\ge$ 4% of total staked AWP.

  9. WorkNet Manager Roles and AWP Strategies

    main

    Role System

    The WorkNet Manager uses a role-based access control system:

    RoleHashPurpose
    DEFAULT_ADMIN_ROLE0x00...00Grant/revoke all roles
    MERKLE_ROLEkeccak256("MERKLE_ROLE")Batch mint, set Merkle root
    TRANSFER_ROLEkeccak256("TRANSFER_ROLE")Batch transfer AWP/tokens
    STRATEGY_ROLEkeccak256("STRATEGY_ROLE")Change AWP strategy
    CHECKPOINT_ROLEkeccak256("CHECKPOINT_ROLE")Submit computation checkpoints
    UPGRADER_ROLEkeccak256("UPGRADER_ROLE")UUPS upgrade (can be permanently renounced)

    AWP Strategy Options

    When the manager receives AWP, it follows one of three AWPStrategy behaviors:

    1. Reserve (0): Holds AWP in the manager for manual distribution via batchTransferTokenPacked.
    2. AddLiquidity (1): Adds AWP and mints Alpha tokens to the LP pool.
    3. BuybackBurn (2): Uses AWP to buy Alpha tokens on the DEX and burns them.

  10. EIP-712 Signing Domains for AWP

    main

    Several AWP operations require EIP-712 signatures. Ensure you use the correct domain and fetch the appropriate nonce before signing.

    AWPRegistry Domain

    Used for: bind, unbind, setRecipient, grantDelegate, revokeDelegate, registerWorknet, activateWorknet.

    {
  "name": "AWPRegistry",
  "version": "1",
  "chainId": <chainId>,
  "verifyingContract": "0x0000F34Ed3594F54faABbCb2Ec45738DDD1c001A"
}

    Nonce: Fetch via nonce.get(address).

    AWPAllocator Domain

    Used for: allocate, deallocate.

    {
  "name": "AWPAllocator",
  "version": "1",
  "chainId": <chainId>,
  "verifyingContract": "0x0000D6BB5e040E35081b3AaF59DD71b21C9800AA"
}

    Nonce: Fetch via nonce.getStaking(address).

  11. Perform cross-chain allocations using worknetId

    main
    Allocations are local to the chain where they are performed, but the worknetId is globally unique across the entire protocol. This allows for cross-chain interaction; for example, a user on Ethereum can allocate veAWP to a WorkNet located on Base by referencing its unique worknetId.

  12. Calculate veAWP Voting Power

    main

    Voting power for veAWP positions is calculated using a time-weighted formula that caps the weight at 54 weeks.

    Formula: votingPower = amount * sqrt(min(remainingTime, 54 weeks) / 7 days)

    Variables:

    • remainingTime: lockEndTime - block.timestamp (in seconds).
    • 54 weeks: 32,659,200 seconds (the MAX_WEIGHT_SECONDS cap).
    • 7 days: 604,800 seconds (the base unit for the square root calculation).

    Note: Calculations use Unix timestamps, not epoch numbers.