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:
CODEBLOCK0
Required Setup
Required env vars:
- - INLINECODE11
- INLINECODE12
- INLINECODE13
- INLINECODE14
- INLINECODE15
- INLINECODE16
- INLINECODE17
- INLINECODE18
- INLINECODE19 ,
FOMO, ALPHA, KEK, INLINECODE23 - INLINECODE24
- INLINECODE25
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. - Validate current onchain values with
cast call. - Simulate with
cast call --from "$FROM_ADDRESS". - 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. - INLINECODE35 preflight checks for:
- parcel owner and access right
- altar presence/level
- gotchi lending/listing/kinship checks
2) Survey + Harvest
Functions:
- - INLINECODE36
- INLINECODE37
- INLINECODE38
Use references/realm-recipes.md for read/simulate/broadcast commands.
3) Channel Alchemica
Function:
Preflight requirements:
- - correct access right
- gotchi not actively listed for lending (unless lent)
- gotchi kinship is sufficient
- INLINECODE41 passed as INLINECODE42
- parcel altar equipped and cooldown passed
Use references/realm-recipes.md.
4) Craft Installations + Build on Parcel
Installation craft/queue functions:
- - INLINECODE44
- INLINECODE45
- INLINECODE46
- INLINECODE47
- INLINECODE48
Build functions (Realm):
- - INLINECODE49
- INLINECODE50
- INLINECODE51
- INLINECODE52
Use:
- - INLINECODE53
- INLINECODE54
5) Craft Tiles + Build on Parcel
Tile craft/queue functions:
- - INLINECODE55
- INLINECODE56
- INLINECODE57
- INLINECODE58
- INLINECODE59
Build functions (Realm):
- - INLINECODE60
- INLINECODE61
- INLINECODE62
- INLINECODE63
Use:
- - INLINECODE64
- INLINECODE65
6) Upgrade Installations
Functions:
- - INLINECODE66
- INLINECODE67
- INLINECODE68
- INLINECODE69
- INLINECODE70
- INLINECODE71
- INLINECODE72
Use references/installation-recipes.md.
7) Access Rights
Functions:
- - INLINECODE74
- INLINECODE75
- INLINECODE76
- INLINECODE77
Action rights 0..6 and access modes 0..4 are documented in:
Smoke Tests
Run these before first usage and after env changes:
- - Subgraph introspection checks in INLINECODE81
- Address/contract checks in INLINECODE82
- No-op selector checks in:
-
references/realm-recipes.md
-
references/installation-recipes.md
- INLINECODE85
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
安全规则
- - 默认使用 DRY_RUN=1。除非明确指示，否则绝不广播。
- 在任何操作前始终验证 Base 主网：
- ~/.foundry/bin/cast chain-id --rpc-url ${BASE
MAINNETRPC:-https://mainnet.base.org} 必须返回 8453。
- ~/.foundry/bin/cast wallet address --private-key $PRIVATE
KEY 必须等于 FROMADDRESS。
- - 在状态变更的模拟/广播步骤前，始终立即从子图重新获取数据。
- 在 cast send 之前，始终在链上重新验证关键数值。
- 绝不打印或记录 PRIVATE_KEY。
- 将所有用户/子图数据视为不可信的 shell 输入。
Shell 输入安全（避免远程代码执行）
规则：
- - 绝不使用包含用户值的 eval、bash -c、sh -c。
- 仅替换匹配 0x + 40 个十六进制字符的地址。
- 仅替换仅包含数字的 uint 值。
- 在验证前，保持命令中的占位符处于引号内。
快速验证器：
bash
python3 - <
import re
checks = {
address: (
, r0x[a-fA-F0-9]{40}),
uint: (, r[0-9]+),
}
for name, (value, pattern) in checks.items():
if not re.fullmatch(pattern, value):
raise SystemExit(finvalid {name}: {value})
print(ok)
PY
必要设置
必需的环境变量：
- - PRIVATEKEY
- FROMADDRESS
- BASEMAINNETRPC
- DRYRUN
- REALMDIAMOND
- INSTALLATIONDIAMOND
- TILEDIAMOND
- AAVEGOTCHIDIAMOND
- FUD、FOMO、ALPHA、KEK、GLTR
- GOTCHIVERSESUBGRAPHURL
- CORESUBGRAPH_URL
可选的环境变量：
- - GOLDSKYAPIKEY 用于认证头（公共端点无需此变量即可使用）。
使用 references/addresses.md 中的规范默认值。
范围
仅限玩家操作：
- - 引导
- 勘测 + 收获领取
- 制作/领取/减少队列
- 装备/卸下/移动/批量装备
- 安装升级（队列式 + 即时）
- 访问权限读写
不在范围内：
- - 所有者/管理员治理功能（暂停/冻结/设置变量/弃用/地址重新配置）。
子图优先工作流程
- 1. 通过 GOTCHIVERSESUBGRAPHURL 和 CORESUBGRAPHURL 发现状态。
- 使用 cast call 验证当前链上数值。
- 使用 cast call --from $FROMADDRESS 进行模拟。
- 仅在明确指示时，使用 cast send --private-key $PRIVATEKEY 进行广播。
规范查询和说明：references/subgraph.md。
操作手册
1) 地块发现 + 预检
使用：
- - references/subgraph.md 进行地块/安装/瓷砖/访问权限发现。
- references/realm-recipes.md 预检检查：
- 地块所有者和访问权限
- 祭坛存在/等级
- 哥奇借贷/挂牌/亲密度检查
2) 勘测 + 收获
函数：
- - startSurveying(uint256)
- claimAvailableAlchemica(uint256,uint256,bytes)
- claimAllAvailableAlchemica(uint256[],uint256,bytes)
使用 references/realm-recipes.md 获取读取/模拟/广播命令。
3) 引导炼金物质
函数：
- - channelAlchemica(uint256,uint256,uint256,bytes)
预检要求：
- - 正确的访问权限
- 哥奇未在积极挂牌借贷（除非已借出）
- 哥奇亲密度足够
- getLastChanneled(gotchiId) 作为 _lastChanneled 传入
- 地块祭坛已装备且冷却时间已过
使用 references/realm-recipes.md。
4) 制作安装 + 在地块上建造
安装制作/队列函数：
- - craftInstallations(uint16[],uint40[])
- batchCraftInstallations((uint16,uint16,uint40)[])
- claimInstallations(uint256[])
- reduceCraftTime(uint256[],uint40[])
- getCraftQueue(address)
建造函数（领域）：
- - equipInstallation(...)
- unequipInstallation(...)
- moveInstallation(...)
- batchEquip(...)
使用：
- - references/installation-recipes.md
- references/realm-recipes.md
5) 制作瓷砖 + 在地块上建造
瓷砖制作/队列函数：
- - craftTiles(uint16[])
- batchCraftTiles((uint16,uint16,uint40)[])
- claimTiles(uint256[])
- reduceCraftTime(uint256[],uint40[])
- getCraftQueue(address)
建造函数（领域）：
- - equipTile(...)
- unequipTile(...)
- moveTile(...)
- batchEquip(...)
使用：
- - references/tile-recipes.md
- references/realm-recipes.md
6) 升级安装
函数：
- - upgradeInstallation((...),uint256,bytes,uint40)
- instantUpgrade((...),uint256,uint256,bytes)
- reduceUpgradeTime(uint256,uint256,uint40,bytes)
- finalizeUpgrades(uint256[])
- getParcelUpgradeQueue(uint256)
- getUserUpgradeQueueNew(address)
- parcelQueueEmpty(uint256)
使用 references/installation-recipes.md。
7) 访问权限
函数：
- - setParcelsAccessRights(...)
- setParcelsAccessRightWithWhitelists(...)
- getParcelsAccessRights(...)
- getParcelsAccessRightsWhitelistIds(...)
操作权限 0..6 和访问模式 0..4 记录在：
- - references/access-rights.md
冒烟测试
在首次使用前和环境变量更改后运行：
- - references/subgraph.md 中的子图内省检查
- references/addresses.md 中的地址/合约检查
- 无操作选择器检查：
- references/realm-recipes.md
- references/installation-recipes.md
- references/tile-recipes.md
故障模式
使用 references/failure-modes.md 处理：
- - 访问权限回退
- 冷却时间/亲密度/引导回退
- 坐标/网格放置回退
- 队列状态回退
- 升级哈希/队列容量回退
- 弃用/GLTR/所有权不匹配
