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: ```bash 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