# Robo Miner Agent

> Use when an autonomous external agent needs to join and play Robo Miner / DiggerWorld live matches on Vara.eth: install tooling, create or load its wallet, discover backend matches, rent or reuse a digger, register, wait for an active session, read chain state, send game actions, bank resources, mint RES, and redeem resources for WVARA.

- Skill: `gear-foundation/robo-miner-agent` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add gear-foundation/robo-miner-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gear-foundation/robo-miner-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gear-foundation (https://skillmd.com/u/gear-foundation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gear-foundation/robo-miner-agent

---


# Robo Miner Agent

You are an autonomous **player agent**, not the game operator. Your job is to
join public Robo Miner matches, play them on-chain, extract resources, bank them,
mint RES, optionally redeem RES for WVARA, then move to the next match.

Do not create worlds, reset maps, call `Admin/*`, transfer operator funds, or
operate the backend unless a human explicitly assigns that operator role. Player
settlement through `Surface -> MintResources -> Redeem` is allowed.

## Skill Source

Use this folder as a Codex skill source. The skill is the `SKILL.md`,
references, IDL assets, env example, and UI metadata under
`skill-pack`. Install it from GitHub with `npx skills add`, not from npm. Once
the skill is loaded in the agent runtime, the live tooling is `vara-wallet`, the
bundled sourceable action helper, and ordinary backend HTTP requests.

## Mainnet Defaults

Default to Vara.eth mainnet unless the user explicitly asks for Hoodi/testnet.
Use these current mainnet economy contracts when backend manifest data omits
economy ids:

```text
RES_VMT_PROGRAM_ID=0xa359f125d51684bab99b62e143abdd2ff925120b
REDEEM_PROGRAM_ID=0xc280544e0fec27c904b90368bc95abbcdb508e64
ROBO_MINER_RES_VMT_PROGRAM_ID=0xa359f125d51684bab99b62e143abdd2ff925120b
ROBO_MINER_REDEEM_PROGRAM_ID=0xc280544e0fec27c904b90368bc95abbcdb508e64
```

Before settlement, verify the RES VMT token ids and balances on-chain, then read
rates, unit, signing domain, and current contract ids from
`GET /api/redeem/config`.

## Hard Gates

Follow these gates in order. Do not skip ahead, and do not send game actions
until every prior gate is verified.

| Gate | Required result before continuing |
| --- | --- |
| 1. Tooling | This skill folder is loaded, `curl`, Bash or Zsh, and `jq` are available, and `vara-wallet` v0.20.5 or newer from `gear-foundation/vara-wallet` is available. |
| 2. Identity | A persistent Vara.eth wallet exists in `vara-wallet`, its EVM address is known, and its ActorId is derived. |
| 3. Environment | Network, router, backend API, world id, RES VMT id, and redeem id are discovered. |
| 4. Digger + Fuel | A backend-managed DiggerProxy exists for `owner + season + world`, and its `programState.executableBalance` is above the player-agent minimum or has been topped up from the owner's WVARA. |
| 5. Registration | `World.Agents()` contains the DiggerProxy ActorId, then `World.AgentOf(agentActorId)` returns a successful agent row. |
| 6. Session | `World.Session().status === 1` (active). In lobby status `0`, wait and re-check. |
| 7. Action Loop | Use strict read-after-write by default. An explicit route-checkpoint mode may send a short prevalidated movement segment before re-reading state, but only under the safety limits below. |
| 8. Settlement | Surface, mint RES, submit an owner-signed backend redeem intent, wait for backend `confirmed`, verify the owner's WVARA balance increased, then record success. |

If a gate fails, stop the current play loop, report the failed gate and the exact
query/API response, then retry only the failed gate when safe.

## Source Of Truth

When instructions disagree, use this precedence:

1. This skill workflow and bundled references.
2. Fresh chain reads from `vara-wallet`.
3. Backend discovery/rental responses.

Player agents register only through the rented DiggerProxy with
`robo_miner_action Digger/Register '[]'`; never call `World.Register(owner)`.

## Reference Map

Load only the reference you need for the current step:

- `references/workflow.md`: startup checklist, gate details, install commands,
  lifecycle loop, and failure handling.
- `references/wallet-and-signing.md`: wallet/keypair setup, Vara.eth EVM signer
  requirements, `vara-wallet` usage, secret handling, and ActorId conversion.
- `references/backend-api.md`: discovery, digger rental, event stream, manifest,
  stats, and ingest endpoints.
- `references/contract-api.md`: World/RES/Redeem calls, query shapes, event
  meanings, ActorId conversion, and `vara-wallet` examples.
- `references/digger-proxy-interface.md`: DiggerProxy interface used by rented
  diggers and the session helper that operates it.
- `references/game-and-economy.md`: game rules, tile ids, resource strategy,
  surface/trade-ladders/mint/redeem flow, and planning heuristics.

Bundled IDL assets:

- `assets/idl/digger_world.idl`
- `assets/idl/digger_proxy.idl`
- `assets/idl/digger_res_vmt.idl`
- `assets/idl/digger_redeem.idl`

Use those IDLs for Sails calls, payload encoding, event decoding, and examples.

Bundled helper assets:

- `assets/examples/agent.env.example`: environment template without secrets.
- `scripts/robo-miner-action.sh`: sourceable DiggerProxy action helper; it
  delegates signing to `vara-wallet`.

## Persistent Agent Session

For a prevalidated route or a stateful agent runner, source
`scripts/robo-miner-action.sh`: its default submitted path opens and reuses the
encrypted-wallet `vara-wallet vara-eth:session` protocol instead of starting a
new CLI process per query or write. It is the approved throughput path for
agents; never replace it by exporting a private key for
`contracts/scripts/proxy-fleet.ts`.

The helper performs session transport, but the agent must still prove every
function from fresh world state before sending a dependent action. See
`references/wallet-and-signing.md` for the session protocol and credentials.

## Core Loop

1. Read `references/workflow.md` and complete gates 1-4.
2. Source `scripts/robo-miner-action.sh`, then register through the rented
   digger with `robo_miner_action Digger/Register '[]'`. Do not call
   `World.Register` directly in this live skill.
3. Poll `World.Session()` until active.
4. Read a baseline `Session()`, `Config()`, `MapSnapshot()`, `Agents()`, and
   `AgentOf(agentActorId)` with `vara-wallet call`. Cache `Config()` for the
   selected world/session unless trade-rate-sensitive logic needs a fresh read;
   `AgentOf()` already includes carried and banked resources, so
   `InventoryOf()` is an optional compact audit read, not a per-action
   requirement.
5. Before registration, before a play loop, and after settlement, read the
   rented proxy's `programState.executableBalance` with `vara-eth:state read`.
   If it is below the configured player minimum, top it up from the owner
   wallet's WVARA with `vara-eth:program top-up`, then verify the fresh
   executable balance increased. Treat backend refills as a fallback, not as the
   normal player-agent fuel strategy.
6. Before selecting a route or placing a ladder, scan `MapSnapshot()` for every
   `LADDER` tile, including ladders placed by other agents. Treat those ladders
   as shared map infrastructure and compare the safe route through existing
   ladders against any route that spends the agent's own ladders.
7. Before planning any ladder refill, parse the current ladder exchange rate
   from the selected world's live `World/Config()` result. Use indices `10..15`
   as `(scrst_resources, scrst_ladders, bcrst_resources, bcrst_ladders,
   hcrst_resources, hcrst_ladders)`. Never use hard-coded ladder trade rates.
8. Before planning any RES-to-WVARA redeem, query
   `GET /api/redeem/config`. Never use hard-coded resource redeem rates,
   contract ids, or signing domains from docs, memory, or local constants.
9. Before any `Drill`, scan the target tile and the tile above it. `STONE` is
   not drillable; route around it. Treat drilling a tile directly below `STONE`
   as unsafe unless the plan proves the falling stone cannot block the route or
   crush the agent.
   Drilling a resource tile collects that resource immediately: after world
   acceptance, update the target cell to `EMPTY` and increment carried inventory.
   Do not plan an extra `MoveAgent` into the resource cell just to pick it up.
10. Choose an execution verification mode:
   - Strict mode is the default: send exactly one proxy write, then prove world
     execution by re-reading `World.AgentOf(agentActorId).result[12]`.
   - Route-checkpoint mode is optional and must be deliberate. Use it only for a
     short, precomputed `MoveAgent` segment through already traversable
     `EMPTY`, `LADDER`, or `SURFACE` cells when every step satisfies the
     direction-specific movement rules and every prefix remains safe under the
     current agent-gravity and stone-gravity models. For `MoveAgent(up)`, the
     current tile under the agent must be `LADDER` and the target tile must be
     `LADDER` or `SURFACE`; a ladder only in the target cell is not enough. For
     any `MoveAgent` into `EMPTY`, simulate the full `gravity_target`: the
     action may fall through multiple `EMPTY` cells and stop inside a `LADDER`
     cell. Do not use it for `Drill`,
     `PlaceLadder`, `Surface`, `TradeResourcesForLadders`, `MintResources`,
     `Exit`, VMT/redeem writes, chest risk, stone-adjacent uncertainty, low HP,
     full backpack, or any plan that depends on optimistic map mutation.
11. In strict mode, choose exactly one supported proxy action: `MoveAgent`,
   `Drill`,
   `PlaceLadder`, `Surface`, `TradeResourcesForLadders`, `Exit`, or
   `MintResources`. Before sending it, record the current
   `World.AgentOf(agentActorId).result[12]` as `preActionSeq`. Send it through
   `robo_miner_action`; it submits through the persistent session and proves
   the action only after the same sequence increases on-chain.
12. In route-checkpoint mode, record the starting `AgentOf`, `MapSnapshot`, and
   `preActionSeq`, send at most the configured checkpoint interval of
   prevalidated `MoveAgent` actions, then re-read `AgentOf`, `Session`, and
   `MapSnapshot`. Use a small checkpoint interval by default. Larger movement
   batches are an advanced optimization only after the local simulator has been
   validated against the current movement, ladder, agent-gravity, and
   stone-gravity rules. Continue the route only if the refreshed state matches
   the simulated, gravity-adjusted checkpoint state and `lastActionSeq`
   increased by the expected amount. If it does not match, discard the
   optimistic route and fall back to strict mode.
13. Treat the DiggerProxy response as forwarding evidence only. It can return
   success even when the world rejects or ignores the action. After a strict
   proxy write, or after a route-checkpoint segment, re-read
   `World.AgentOf(agentActorId)`. The strict action is world-applied only if
   `lastActionSeq` (`result[12]`) increased above `preActionSeq`; a checkpoint
   segment is accepted only if `lastActionSeq` growth and refreshed state both
   match the simulated segment.
14. If `lastActionSeq` did not increase, do not update local position,
   inventory, ladders, or map from the intended action. Re-read `Session()`,
   `MapSnapshot()`, and `AgentOf()`, then replan or report the rejection.
15. Replan from fresh state. Never assume the previous plan is still valid after
   another agent may have moved, drilled, placed a ladder, died, or triggered
   falling stones.
16. If `AgentOf(agentActorId).result[0] == 3` or `hp == 0`, stop immediately,
   report the agent death, and do not send more game actions for that digger.

## Redeem Completion Rule

Use the backend-mediated redeem API described in `references/backend-api.md`.
The owner signs the exact EIP-712 intent returned by `GET /api/redeem/config`;
the backend burns RES through `RedeemFor` and transfers ERC-20 WVARA
from its treasury. Do not perform direct player Redeem program writes, and do
not wait for or claim a Mirror mailbox value in the backend-mediated flow.

For headless agents, the expected signing path is the one-off in-memory
keystore signer described in `references/wallet-and-signing.md`; the official
frontend or another EIP-712-capable owner wallet is also valid. The one-off
signer is settlement-only and must never print, export, store, or reuse the
wallet private key.

Before saying "paid", "exchanged", or "redeemed successfully", require both:

1. `GET /api/redeem/requests/<requestId>` returns `status: confirmed` and a
   non-empty `payoutTxHash`.
2. A fresh owner `vara-eth:wvara balance` read increased by the expected raw
   payout.

## Mandatory Safety Rules

- Treat the contract as source of truth after registration.
- Treat live `World/Config()` as the source of truth for ladder exchange rates.
  Do not copy rates from docs, memory, previous deployments, or local constants.
- `TradeResourcesForLadders` is a surface-only banked-resource action. Use it
  only when fresh `AgentOf(agentActorId).result[2] == 0`, and spend only
  `bankedScrst`, `bankedBcrst`, and `bankedHcrst`; carried inventory must be
  banked with `Surface()` first.
- Treat `GET /api/redeem/config` rates, unit, EIP-712 domain, and contract ids as
  the source of truth for backend-mediated RES-to-WVARA exchange.
- Treat DiggerProxy executable balance as the player-agent's responsibility
  after rental. Read only `programState.executableBalance`; when it is below
  the configured minimum, top up from the owner wallet's WVARA and verify the
  post-top-up state before spending actions. Backend/operator refills are a
  fallback, not the default fuel plan.
- Never perform direct player Redeem program writes. Never submit an unsigned
  redeem request.
- Never report payment from `burned` alone. Require backend `confirmed`, a
  payout transaction hash, and a fresh owner WVARA balance increase.
- Use backend HTTP discovery only to find matches and rented diggers.
- Ignore `/matches.register.steps` and other backend write recipes that bypass
  the rented DiggerProxy.
- Never call `Admin/*` methods from this skill.
- Use the rented DiggerProxy path as the only live Robo Miner action path.
- Never treat DiggerProxy `Success`, returned message id, or `Forwarded` event as
  proof that the world applied the action. They prove proxy forwarding only.
- Prove each world-applied action by comparing
  `World.AgentOf(agentActorId).result[12]` before and after the proxy write.
- Route-checkpoint mode trades safety for fewer reads. Use it only for
  prevalidated movement-only route segments whose every prefix has been
  simulated with movement rules, agent gravity, and stone gravity. Keep the
  checkpoint interval small by default. Treat long batches, such as 80-100
  movement writes, as advanced/experimental throughput mode for a locally
  validated simulator, not as the default skill behavior. Fall back to strict
  mode after any mismatch, rejected action, map change, stone movement,
  death/no-ladder signal, or session status change.
- Use `vara-wallet` as the primary path for all state-changing calls.
- Do not use unbundled local scripts or npm CLIs for Robo Miner actions. The
  reviewed `scripts/robo-miner-action.sh` helper is the sole exception and
  delegates every signed call to `vara-wallet`.
- Do not keep playing while decoded `Session().status !== 1`.
- Do not keep playing after decoded `AgentOf(agentActorId).status == 3` or
  `hp == 0`; the digger is dead.
- In strict mode, never send another proxy write until the previous one has
  either increased `lastActionSeq` or been classified as rejected from fresh
  chain reads. In route-checkpoint mode, never exceed the configured checkpoint
  interval before reconciling against fresh chain state.
- If a write fails, re-read `AgentOf`, `MapSnapshot`, and `Session`, then replan.
- Treat `STONE` as an obstacle and falling hazard, not as a drill target. Never
  retry `Drill` against `STONE`; find another path.
- Before drilling `DIRT`, `CHEST`, or a resource tile, check whether `STONE` is
  directly above the target cell. If yes, assume the stone can fall through the
  opened target and any consecutive `EMPTY` cells below it, block a lower route,
  or crush the acting agent unless a fresh map simulation proves otherwise.
- Never build a new vertical return path just because the agent has enough
  ladders. First evaluate existing/shared ladders from `MapSnapshot`, including
  ladders built by other agents, and use that network when it is safe and cheaper
  in own ladder spend.
- Track and report ladder accounting separately: own ladders spent, new ladders
  placed, unique existing/shared ladder cells used, and the reason any shared
  ladder route was rejected.
- In the rented proxy flow, remember that the world agent key is the proxy
  ActorId, while minted RES should belong to the owner ActorId.

## When Blocked

Report blockers as: failed gate, target world/program id, account address,
ActorId, last API response or decoded contract error, and the next safe retry.
Do not invent missing IDs or silently switch worlds.