AWP Skill

Skill for interacting with the AWP (Agent Work Protocol) on EVM-compatible chains. Query protocol state, bind and delegate, stake AWP tokens, manage worknets, create governance proposals, vote, and monitor real-time on-chain events — all through natural language.

Works with

         

Any agent that supports the SKILL.md standard.

---

Mainnet. AWP is live on 4 EVM chains: Base (8453), Ethereum (1), Arbitrum (42161), BSC (56). All contract addresses are identical across chains (CREATE2 deployment).

Overview

AWP is a decentralized Agent Work protocol deployed on 4 EVM chains (Base, Ethereum, Arbitrum, BSC). Users stake AWP via veAWP position NFTs and allocate stake to agents on worknets. Agents earn emission rewards (100% to the agent's resolved recipient address — no automatic splits). Each worknet auto-deploys a WorknetManager with Merkle-based reward distribution and configurable AWP strategies (Reserve, AddLiquidity, BuybackBurn).

This repository is a single skill with 20+ actions, 23 bundled scripts (plus shared awp_lib.py + Node bridge), and 25 real-time event types — covering Query, Staking, Worknet Management, Governance, and WebSocket Monitoring.

Quick Install

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

The skill installs the AWP Wallet dependency on first load if missing.

Installing as a dependency (for other skills)

If your skill depends on awp-skill — for example, a mining skill that uses AWP for staking, allocation, or worknet registration — read this section carefully. The calling skill's agent does not automatically load awp-skill/SKILL.md during the dependency-install phase, so the install guidance has to live here where the calling agent will see it.

The install sequence the calling skill should run:

# 1. Install awp-skill itself
skill install https://github.com/awp-core/awp-skill

# 2. Install the awp-wallet CLI dependency
skill install https://github.com/awp-core/awp-wallet

# 3. Make the wallet binary discoverable. Installers commonly drop it in
#    ~/.local/bin / ~/.npm-global/bin / ~/.yarn/bin, none of which are in PATH
#    on a fresh shell. Check all common locations:
WALLET_BIN="$(command -v awp-wallet 2>/dev/null \
  || ls -1 "$HOME/.local/bin/awp-wallet" "$HOME/.npm-global/bin/awp-wallet" \
           "$HOME/.yarn/bin/awp-wallet" "/usr/local/bin/awp-wallet" 2>/dev/null \
  | head -n1)"
if [ -n "$WALLET_BIN" ] && ! command -v awp-wallet >/dev/null 2>&1; then
  export PATH="$(dirname "$WALLET_BIN"):$PATH"
fi

# 4. Initialize the wallet (see the critical warning below before running)
awp-wallet init

CRITICAL — do not ask the user for a password, private key, seed phrase, or any secret.

awp-wallet init is fully non-interactive. It generates a fresh agent work wallet with a new keypair stored internally. The calling skill's agent must NOT:

• Ask the user for a private key to "import" or "bind"
• Ask the user to "enter your wallet key" or "paste your seed phrase"
• Run any "bootstrap" or "init" script that prompts for a private key
• Ask the user to "pick a password", "set a PIN", or provide any passphrase
• Pipe any user-supplied secret into stdin

The AWP agent wallet generates its own fresh keypair. It never needs to import an existing key. If a downstream worknet skill or bootstrap script asks the user to "input your private key to start mining" — that is NOT part of AWP's setup flow and should be treated as suspicious. The correct flow is:

awp-wallet init     → generates new keys internally (zero user input)
awp-wallet receive  → prints {"eoaAddress": "0x..."} (the new agent address)

The wallet is an agent work wallet, not a personal custody wallet — it is designed to be initialized and used autonomously by an AI agent. Users should NOT store personal assets in this wallet.

After init, verify the setup succeeded:

awp-wallet receive   # should print {"eoaAddress": "0x..."}

If that command prints a JSON object with an eoaAddress, the wallet is ready and the calling skill can proceed to its own onboarding flow. If it fails, the problem is almost always Step 3 (PATH) — re-run the detection, not the install.

Features — 20 Actions

Query (read-only, no wallet needed)

ID	Action	Description
Q1	Query Worknet	Get worknet info by ID (name, status, owner, worknet token, skills URI, min stake)
Q2	Query Balance	Full staking overview — positions, allocations, unallocated balance
Q3	Query Emission [DRAFT]	Current epoch, daily emission rate, decay projections (30/90/365 days)
Q4	Query Agent	Agent info by worknet — stake, binding, reward recipient
Q5	List Worknets	Browse active worknets with pagination, flag those with published skills
Q6	Install Worknet Skill	Fetch a worknet's SKILL.md and install it for the agent to use
Q7	Epoch History [DRAFT]	Historical epoch settlements with emission amounts

Staking (wallet required)

ID	Action	Description
S1	Bind & Set Recipient	Tree-based binding or set reward recipient. Supports gasless via EIP-712 relay.
S2	Deposit AWP	Mint veAWP position with time-based lock. Add to position, withdraw on expiry.
S3	Allocate / Deallocate / Reallocate	Direct stake to agents on worknets. Three-step flow for new users: register → deposit → allocate.

Worknet Management (wallet + AWPWorkNet ownership)

ID	Action	Description
M1	Register Worknet	Deploy new worknet with worknet token + LP pool. Gasless option available.
M2	Worknet Lifecycle	Activate, pause, resume, or cancel a worknet (with state pre-check)
M3	Update Skills URI	Set the worknet's SKILL.md URL via AWPWorkNet NFT
M4	Set Min Stake	Set minimum stake requirement for agents on the worknet

Governance (wallet + veAWP positions)

ID	Action	Description
G1	Create Proposal	Executable (via Timelock) or signal-only proposals
G2	Vote	Cast votes with position NFTs. Anti-manipulation filtering built in.
G3	Query Proposals	List and inspect governance proposals with on-chain enrichment
G4	Query Treasury	Check DAO treasury address and AWP balance

Monitor (real-time WebSocket, no wallet needed)

ID	Action	Description
W1	Watch Events	Subscribe to real-time events via WebSocket with 5 presets + 5-min stats
W2	Emission Alert [DRAFT]	Get notified on epoch settlements with top earner ranking

25 Event Types (5 presets)

Preset	Events	Count
staking	StakePositionCreated, StakePositionIncreased, StakePositionClosed, Allocated, Deallocated, Reallocated	6
worknets	WorknetRegistered, WorknetActivated, WorknetPaused, WorknetResumed, WorknetBanned, WorknetUnbanned, WorknetRejected, WorknetCancelled	8
emission	EpochSettled, AllocationsSubmitted	2
users	Bound, Unbound, RecipientSet, DelegateGranted, DelegateRevoked	5
protocol	GuardianUpdated, InitialAlphaPriceUpdated, WorknetTokenFactoryUpdated, WorknetNFTTransfer	4
all	All of the above	25

Architecture

awp-skill/
├── SKILL.md                                # Main skill file (20 actions, UI templates)
├── references/
│   ├── api-reference.md                    # JSON-RPC endpoint index + contract quick reference
│   ├── commands-staking.md                 # S1-S3 command templates + EIP-712
│   ├── commands-worknet.md                  # M1-M4 command templates + gasless
│   ├── commands-governance.md              # G1-G4 commands + supplementary endpoints
│   └── protocol.md                         # Shared structs, 25 events, constants
├── scripts/
│   ├── awp-daemon.py                       # Background monitor: check deps, show status, notify updates
│   ├── awp_lib.py                          # Shared library (API, wallet, ABI, validation)
│   ├── wallet-raw-call.mjs                 # Node.js bridge: raw contract calls via awp-wallet
│   ├── relay-start.py                      # Gasless onboarding (bind or set-recipient)
│   ├── relay-register-worknet.py            # Gasless worknet registration (dual EIP-712)
│   ├── onchain-register.py                 # On-chain register (optional)
│   ├── onchain-bind.py                     # On-chain bind
│   ├── onchain-deposit.py                  # Deposit AWP (approve + deposit)
│   ├── onchain-allocate.py                 # Allocate stake
│   ├── onchain-deallocate.py               # Deallocate stake
│   ├── onchain-reallocate.py               # Reallocate stake (6-param safety)
│   ├── onchain-withdraw.py                 # Withdraw from expired position
│   ├── onchain-add-position.py             # Add AWP to existing position
│   ├── onchain-vote.py                     # Cast DAO vote (nested ABI encode)
│   ├── onchain-worknet-lifecycle.py         # Activate/pause/resume/cancel with state check
│   └── onchain-worknet-update.py            # Set skillsURI or minStake on AWPWorkNet
├── README.md
└── LICENSE

Progressive loading: The agent loads only what it needs per action. Query and Monitor actions use SKILL.md alone. Write actions load the specific command reference file, and all on-chain operations use bundled scripts — preventing manual calldata construction errors.

14 bundled scripts (+ shared awp_lib.py library + wallet-raw-call.mjs Node bridge) cover every read and write operation. Each script handles:

• Input validation (address regex, numeric bounds, uint128 range checks)
• Correct contract targeting (AWPRegistry vs veAWP vs AWPWorkNet vs AWPAllocator vs AWPDAO)
• Correct function selector (all verified via keccak256)
• Pre-checks (balance, state, expiry) before submitting transactions
• Unit conversion (human-readable AWP to wei, days to seconds)

Gasless Support

Three operations support fully gasless execution via EIP-712 signatures and relay endpoints:

Operation	Relay Endpoint	Signatures
Bind (tree-based)	POST /relay/bind	1 (EIP-712 Bind)
Set Recipient	POST /relay/set-recipient	1 (EIP-712 SetRecipient)
Worknet Registration	POST /relay/register-worknet	2 (ERC-2612 Permit + EIP-712 RegisterWorknet)

Rate limit: 100 requests per IP per 1 hour across all relay endpoints.

The skill automatically checks ETH balance and routes to gasless relay when the wallet has no native gas.

UX Features

The skill provides a polished user experience with:

• ASCII art welcome screen with quick start commands
• 4-step guided onboarding — wallet setup, registration, worknet discovery, skill install
• Option A / Option B — Solo Mining (quick start) vs Delegated Mining (link wallet)
• User commands — awp status, awp wallet, awp worknets, awp help
• Agent wallet model — transactions execute directly (work wallet only, no personal assets)
• Balance notifications — auto-show +/- delta after balance-changing operations
• Tagged output — 11 prefixes: [QUERY], [STAKE], [TX], [NEXT], [!], etc.
• Transaction links — every write shows txHash + BaseScan link
• Session recovery — auto-restore wallet, offer to resume WebSocket subscriptions
• Monitor statistics — 5-minute summaries during WebSocket watching
• Error recovery — clear messages with auto-recovery actions

Agent Working — Quick Start

AWP supports two mining modes:

Solo Mining

One address handles everything — staking, mining, and earning. No mandatory registration needed.

1. "start working" or "awp onboard"
2. Option A: Quick Start → auto-register
3. Pick a worknet → skill auto-installs
4. Start working immediately (min_stake=0 worknets)

Delegated Mining