aavegotchi-gotchiverse

Safety Rules

• Default to DRY_RUN=1. Never broadcast unless explicitly instructed.
• Always verify Base mainnet before any action:
• ~/.foundry/bin/cast chain-id --rpc-url "${BASE_MAINNET_RPC:-https://mainnet.base.org}" must be 8453.
• Always verify key/address alignment before any broadcast:
• ~/.foundry/bin/cast wallet address --private-key "$PRIVATE_KEY" must equal FROM_ADDRESS.
• Always refetch from subgraph immediately before state-changing simulate/broadcast steps.
• Always revalidate critical values onchain right before cast send.
• Never print or log PRIVATE_KEY.
• Treat all user/subgraph values as untrusted shell input.

Shell Input Safety (Avoid RCE)

Rules: - Never use eval, bash -c, sh -c with user values. - Only substitute addresses matching 0x + 40 hex chars. - Only substitute uint values containing digits only. - Keep placeholders quoted in commands until validated.

Quick validators:

python3 - <<'PY'
import re

checks = {
  "address": ("<ADDRESS>", r"0x[a-fA-F0-9]{40}"),
  "uint": ("<UINT>", r"[0-9]+"),
}

for name, (value, pattern) in checks.items():
    if not re.fullmatch(pattern, value):
        raise SystemExit(f"invalid {name}: {value}")

print("ok")
PY

Required Setup

Required env vars: - PRIVATE_KEY - FROM_ADDRESS - BASE_MAINNET_RPC - DRY_RUN - REALM_DIAMOND - INSTALLATION_DIAMOND - TILE_DIAMOND - AAVEGOTCHI_DIAMOND - FUD, FOMO, ALPHA, KEK, GLTR - GOTCHIVERSE_SUBGRAPH_URL - CORE_SUBGRAPH_URL

Optional env vars: - GOLDSKY_API_KEY for auth header (public endpoints work without it).

Use canonical defaults from references/addresses.md.

Scope

Player operations only: - Channeling - Survey + harvest claim - Craft/claim/reduce queues - Equip/unequip/move/batch equip - Installation upgrades (queued + instant) - Access-right read/write

Out of scope: - Owner/admin governance functions (pause/freeze/set vars/deprecations/address reconfiguration).

Subgraph-First Workflow

1. Discover state via GOTCHIVERSE_SUBGRAPH_URL and CORE_SUBGRAPH_URL.
2. Validate current onchain values with cast call.
3. Simulate with cast call --from "$FROM_ADDRESS".
4. Broadcast with cast send --private-key "$PRIVATE_KEY" only when explicitly instructed.

Canonical queries and notes: references/subgraph.md.

Runbooks

1) Parcel Discovery + Preflight

Use: - references/subgraph.md for parcel/installations/tiles/access-right discovery. - references/realm-recipes.md preflight checks for: - parcel owner and access right - altar presence/level - gotchi lending/listing/kinship checks

2) Survey + Harvest

Functions: - startSurveying(uint256) - claimAvailableAlchemica(uint256,uint256,bytes) - claimAllAvailableAlchemica(uint256[],uint256,bytes)

Use references/realm-recipes.md for read/simulate/broadcast commands.

3) Channel Alchemica

Function: - channelAlchemica(uint256,uint256,uint256,bytes)

Preflight requirements: - correct access right - gotchi not actively listed for lending (unless lent) - gotchi kinship is sufficient - getLastChanneled(gotchiId) passed as _lastChanneled - parcel altar equipped and cooldown passed

Use references/realm-recipes.md.

4) Craft Installations + Build on Parcel

Installation craft/queue functions: - craftInstallations(uint16[],uint40[]) - batchCraftInstallations((uint16,uint16,uint40)[]) - claimInstallations(uint256[]) - reduceCraftTime(uint256[],uint40[]) - getCraftQueue(address)

Build functions (Realm): - equipInstallation(...) - unequipInstallation(...) - moveInstallation(...) - batchEquip(...)

Use: - references/installation-recipes.md - references/realm-recipes.md

5) Craft Tiles + Build on Parcel

Tile craft/queue functions: - craftTiles(uint16[]) - batchCraftTiles((uint16,uint16,uint40)[]) - claimTiles(uint256[]) - reduceCraftTime(uint256[],uint40[]) - getCraftQueue(address)

Build functions (Realm): - equipTile(...) - unequipTile(...) - moveTile(...) - batchEquip(...)

Use: - references/tile-recipes.md - references/realm-recipes.md

6) Upgrade Installations

Functions: - upgradeInstallation((...),uint256,bytes,uint40) - instantUpgrade((...),uint256,uint256,bytes) - reduceUpgradeTime(uint256,uint256,uint40,bytes) - finalizeUpgrades(uint256[]) - getParcelUpgradeQueue(uint256) - getUserUpgradeQueueNew(address) - parcelQueueEmpty(uint256)

Use references/installation-recipes.md.

7) Access Rights

Functions: - setParcelsAccessRights(...) - setParcelsAccessRightWithWhitelists(...) - getParcelsAccessRights(...) - getParcelsAccessRightsWhitelistIds(...)

Action rights 0..6 and access modes 0..4 are documented in: - references/access-rights.md

Smoke Tests

Run these before first usage and after env changes: - Subgraph introspection checks in references/subgraph.md - Address/contract checks in references/addresses.md - No-op selector checks in: - references/realm-recipes.md - references/installation-recipes.md - references/tile-recipes.md

Failure Modes

Use references/failure-modes.md for: - access-right reverts - cooldown/kinship/channeling reverts - coordinate/grid placement reverts - queue state reverts - upgrade hash/queue capacity reverts - deprecation/GLTR/ownership mismatches