Govnet

GovNet (EMG Protocol) Skill

A natural-language interface for the EMG (Epistemic Market Gauge) prediction-market protocol — also known as GovNet. The skill exposes every user-facing operation: list and watch markets, place and cancel orders, cast private votes during the voting window, split chips into shares (or merge them back), monitor live order books and fills, and read settlement results.

The skill is signing-aware. State-changing requests are gated by an EIP-712 signature produced via awp-wallet sign-typed-data — the skill itself never reads, writes, or stores a private key.

Quick start

1. Install awp-wallet (one-time): awp-wallet --version. If missing, the harness will install it from https://github.com/awp-core/awp-wallet.
2. First-run handshake: the first invocation of any signed script runs GET /v1/auth/info to learn the EIP-712 chain id and verifying contract, then caches both under ~/.govnet/auth-info.json.
3. Public reads work without a wallet:

   python3 scripts/public/markets.py
   python3 scripts/public/book.py --market 6 --worknet 11
   

4. Signed reads/writes auto-resolve principal via awp-wallet receive:

   python3 scripts/private/state.py
   python3 scripts/trade/submit-order.py --market 6 --worknet 11 \
       --side buy --kind limit --price 0.22 --quantity 100
   

End-to-end demo:

$ python3 scripts/helpers/what-can-i-do.py
{
  "phase": "voting_and_trading",
  "epoch_id": 6,
  "next_transition_at": "2026-05-03T12:00:00Z",
  "available": ["list-markets", "vote", "submit-order", "split", "merge", …]
}

API mapping

Every script emits a single JSON object (or one JSON-Lines stream for stream/*) to stdout so the calling agent can parse it directly.

Scripts marked † support a --all-pages flag that walks pagination.next_cursor until exhausted and concatenates all data[] arrays into one response. has_more === false is the authoritative stop signal (see references/api-shapes.md). Default cap is 100 pages — when hit, the output carries truncated_at_max_pages: true plus next_cursor for resume. Private listings still cost one nonce per page (each page is a separately-signed request) — don't blindly enable --all-pages on huge listings.

Endpoints marked sig‡ carry security: [] in OpenAPI (documented as public reads) but production actually requires EMG-SIG-V1 — the skill signs them anyway. The OpenAPI lag is a known doc/server drift; reproduce the auth-required behavior in any reimplementation. The query parameter on /principals/.../state, /principals/.../power, /principals/.../recipient is canonical market_id; epoch_id is accepted as an alias post-9387e78.

Signing (EMG-SIG-V1) — the load-bearing summary

Every authenticated request carries five headers:

Critical contract gotchas — these have all bitten implementers before:

1. Strip the /v1 prefix when populating the path field of the EMGRequest typed data. The production server is mounted under /v1 via axum's Router::nest, which strips the prefix BEFORE the auth middleware sees the URI. Sign /orders, not /v1/orders.
   • Exception: WebSocket auth.hello signs path: "/v1/ws" because the WS handler reads the full URI via a hardcoded literal.
2. WebSocket subscribe param is channels, NOT topics. Server returns INVALID_PARAMS and silently drops every push if you send topics.
3. WS notification field is params.channel, NOT params.topic.
4. BookDelta new_quantity is ABSOLUTE, not a diff. 0 removes the level.
5. Side enum: book channel uses bid/ask; orders use buy/sell.
6. Decimals are strings at scale 18. Carry as strings on the wire; coerce to decimal.Decimal for arithmetic; never use float.
7. Nonce is strictly greater than the server's stored value, tracked per-principal under ~/.govnet/nonces/<principal>.json with atomic rename.
8. AUTH_NONCE_TOO_LOW / NONCE_TOO_LOW retry: re-fetch /v1/auth/info to read the server's stored value, bump local +1, retry once.
9. 5xx with X-EMG-Nonce-Burned: true means the server consumed the nonce even though the request failed. Bump local nonce floor BEFORE retrying.
10. Idempotency keys (X-Idempotency-Key): same key + same body returns cached response within 24 h. Same key + different body → 503 / 409 STATE_IDEMPOTENCY_KEY_MISMATCH (client bug). Generate a fresh key per logical action; reuse on retry.

Full implementation reference: references/signing.md.

Phase awareness

Refuse signed writes early when the current phase doesn't allow them. Fetch /v1/epochs/current (or /v1/epochs/{id}/phase) and check this matrix:

Server-side phase enums use both snake_case (voting_and_trading) and CamelCase (VotingAndTrading); helpers in scripts/lib/govnet_lib.py normalize either form. references/status-state-machine.md has the full map.

Composition with awp-wallet / awp-skill

• awp-wallet is a hard dependency. Every signed request goes through awp-wallet sign-typed-data --data '<json>'. The skill never sees a private key directly. See https://github.com/awp-core/awp-wallet.
• awp-skill is a soft dependency. EMG snapshots veAWP-derived AWP Power at every Wednesday 12:00 UTC. When STATE_PRINCIPAL_NOT_IN_EPOCH fires, the skill should hint at awp-skill rather than try to handle staking itself.

Error handling discipline

Map server code → user-facing action. Every signed-write script has the same retry policy:

Full code → message map: references/error-codes.md (incl. client-emitted codes + post-H3 idempotency section).

Confirm-before-irreversible

Every signed-write script writes a confirmation block to stderr and waits for y on stdin (matching awp-wallet send's pattern):

[TX] about to submit order:
     market:    №6 (aMINE / aGOV / aPRED / aKYA / aARDI / aTMR / aCOM)
     worknet:   aGOV (id 11)
     side:      buy
     kind:      limit @ 0.2200
     quantity:  100
     post_only: false
     reduce_only: false
     stp_mode:  cancel_both
     idem-key:  018f-…
     nonce:     43 (was 42)
     proceed? (y/n)

If stdin is not a tty, the script aborts unless --yes was supplied. NEVER auto-execute a signed write without explicit consent.

Bundled references

Load on demand:

• references/api-shapes.md — request/response shape per endpoint.
• references/signing.md — EMG-SIG-V1 walkthrough with worked examples.
• references/status-state-machine.md — phase transitions + countdown logic.
• references/error-codes.md — full code → user-text map.

Layout

gov-skill/                          # repo root === skill root
├── SKILL.md
├── README.md
├── LICENSE
├── scripts/
│   ├── lib/        # canonical, sign, nonce, ws, govnet_lib
│   ├── public/     # 8 unauthenticated readers
│   ├── private/    # signed reads
│   ├── trade/      # signed writes — orders
│   ├── vote/       # signed writes — votes
│   ├── positions/  # signed writes — split/merge
│   ├── content/    # signed writes — comments / reports
│   ├── stream/     # JSON-Lines WebSocket subscribers
│   └── helpers/    # phase-aware local helpers
├── references/     # markdown loaded on demand by the agent
└── tests/          # pytest — known-answer canonical + EIP-712 digest