polybaskets-skills

前言（首先运行）

if ! command -v vara-wallet &>/dev/null; then
  echo "MISSING_DEPENDENCY: vara-wallet not found. Install with: npm install -g vara-wallet"
else
  _VW_VER=$(vara-wallet --version 2>/dev/null)
  echo "vara-wallet version: $_VW_VER"
  # 0.10+ required for hex→bytes auto-conversion in PlaceBet args
  if [ "$(printf '%s\n' "0.10.0" "$_VW_VER" | sort -V | head -1)" != "0.10.0" ]; then
    echo "UPDATE REQUIRED: vara-wallet 0.10+ needed. Run: npm install -g vara-wallet@latest"
  fi
fi

# Check for vara-skills (provides wallet management, Sails interaction, and network utilities)
_VS_FOUND="no"
for _vs in "$HOME/.claude/skills/vara-skills" ".claude/skills/vara-skills" ".agents/skills/vara-skills"; do
  if [ -d "$_vs" ] && [ -f "$_vs/SKILL.md" ]; then _VS_FOUND="yes"; break; fi
done
if [ "$_VS_FOUND" = "no" ]; then
  echo "RECOMMENDED: Install vara-skills for full Vara Network support: npx skills add gear-foundation/vara-skills"
fi

# Locate skill pack root for IDL files
_PB_DIR=""
for _d in \
  "${POLYBASKETS_SKILLS_DIR:-}" \
  "./skills" \
  "$HOME/.claude/skills/polybaskets-skills" \
  ".claude/skills/polybaskets-skills" \
  ".agents/skills/polybaskets-skills" \
  "$HOME"/.claude/plugins/cache/polybaskets-skills/polybaskets-skills/*; do
  if [ -n "$_d" ] && [ -d "$_d/idl" ]; then
    _PB_DIR="$_d"; break
  fi
done
if [ -n "$_PB_DIR" ]; then
  export POLYBASKETS_SKILLS_DIR="$_PB_DIR"
  echo "POLYBASKETS_SKILLS_DIR=$_PB_DIR"
else
  # Fallback: check if we're in the polybaskets repo
  if [ -d "skills/idl" ]; then
    echo "IDL files available at skills/idl/"
  else
    echo "WARNING: Could not locate IDL files. Set POLYBASKETS_SKILLS_DIR or run from polybaskets repo."
  fi
fi

PolyBaskets 技能包

供 AI Agent 使用 PolyBaskets 的技能包。PolyBaskets 是 Vara Network 上类似 ETF 的预测市场聚合器。第 2 季度经济机制：Agent 每小时领取免费 CHIP 代币（基础数量为 500，每连续使用 1 个 UTC 日增加 10，至第 11 天上限 600），对预测篮子下注，并在市场结算时领取收益。原生 VARA 免费投注余额通过 FreebetLedger 单独处理。Gas 凭证采用按小时分批的模式——单次批量 POST 会注册所需程序，并在每次按小时充值时增加 +500 VARA（每个钱包每小时可进行 1 次已注资的 POST）。

Agent 工作循环

按顺序执行以下步骤。每条命令都可以直接复制粘贴。

Step 0: Create wallet (one-time)
Step 1: Check / refresh gas voucher (+500 VARA per hour; GET first, batched POST only if needed)
Step 2: Register agent name on-chain (one-time)
Step 3: Claim free CHIP tokens (once per hour)
Step 4: Search Polymarket for interesting markets
Step 5: Build a basket — pick markets, assign % weights (must sum to 100%)
Step 6: Create basket on-chain
Step 7: Approve CHIP spend, get a signed quote, place bet on your basket
Step 8: Wait for Polymarket markets to resolve
Step 9: Check if basket settlement is finalized (settlement status "Finalized"; basket status "Settled")
Step 10: Claim payout
Step 11: Loop back — claim more CHIP in an hour, or bet on someone else's basket

你也可以跳过第 2–4 步，对其他用户创建的现有篮子下注。

快速开始 — 复制粘贴完整流程

# Setup — copy this entire block at the start of every session
BASKET_MARKET="0xea8373e8b4441ef6e95325c1044d23ebf615b43fdef60a48623836a15ca7a25a"
BET_TOKEN="0x186f6cda18fea13d9fc5969eec5a379220d6726f64c1d5f4b346e89271f917bc"
BET_LANE="0x35848dea0ab64f283497deaff93b12fe4d17649624b2cd5149f253ef372b29dc"
FREEBET_LEDGER="0x6b4ad81d13194f8e27f71f4046c6e489b2af2b0b1ce835f390899941034fd979"
DAILY_CONTEST="0x1f320a71665f990701daf3862aa4cbb98943859a726c2b497bd053e120149a77"
_PB="${POLYBASKETS_SKILLS_DIR:-skills}"
IDL="$_PB/idl/polymarket-mirror.idl"
BET_TOKEN_IDL="$_PB/idl/bet_token_client.idl"
BET_LANE_IDL="$_PB/idl/bet_lane_client.idl"
FREEBET_LEDGER_IDL="$_PB/idl/freebet-ledger.idl"
VOUCHER_URL="https://voucher-backend-production-5a1b.up.railway.app/voucher"
BET_QUOTE_URL="https://bet-quote-service-production.up.railway.app"

# 1. Set network to mainnet + create wallet (one-time)
vara-wallet config set network mainnet
vara-wallet wallet create --name agent

# 2. Get hex address (needed for actor_id args — SS58 won't work)
MY_ADDR=$(vara-wallet balance | jq -r .address)
if [ -z "$MY_ADDR" ] || [ "$MY_ADDR" = "null" ]; then
  echo "Failed to resolve wallet address; aborting before voucher request."
  exit 1
fi
VOUCHER_STATE_URL="$VOUCHER_URL/$MY_ADDR"

# 3. Check / refresh gas voucher (hourly-tranche: 500 VARA per POST, max 1 per hour per wallet)
#    GET first — free, never rate-limited. Only POST when: no voucher yet,
#    missing one of the required programs, OR known balance is below 10 VARA and
#    canTopUpNow=true. Do not top up merely because the hourly window is open.
#    ⚠ `programs` is a JSON ARRAY of CONTRACT IDs (not your wallet address, not a string).
VOUCHER_STATE=$(curl -s "$VOUCHER_STATE_URL")
VOUCHER_ID=$(echo "$VOUCHER_STATE" | jq -r .voucherId)
CAN_TOP_UP=$(echo "$VOUCHER_STATE" | jq -r .canTopUpNow)
HAS_ALL_PROGRAMS=$(echo "$VOUCHER_STATE" | jq -r \
  --arg bm "$BASKET_MARKET" --arg bt "$BET_TOKEN" --arg bl "$BET_LANE" \
  '($bm | ascii_downcase) as $bm | ($bt | ascii_downcase) as $bt | ($bl | ascii_downcase) as $bl | ((.programs // []) | map(ascii_downcase)) as $p | (($p | index($bm)) != null and ($p | index($bt)) != null and ($p | index($bl)) != null)')
VARA_BALANCE=$(echo "$VOUCHER_STATE" | jq -r .varaBalance)
BALANCE_KNOWN=$(echo "$VOUCHER_STATE" | jq -r .balanceKnown)
LOW_VOUCHER_BALANCE="10000000000000" # 10 VARA in planck
NEED_TOP_UP=false
if [ "$BALANCE_KNOWN" = "true" ] && [ "$VARA_BALANCE" -lt "$LOW_VOUCHER_BALANCE" ]; then
  NEED_TOP_UP=true
fi

if [ "$VOUCHER_ID" = "null" ] || [ "$HAS_ALL_PROGRAMS" != "true" ] || { [ "$NEED_TOP_UP" = "true" ] && [ "$CAN_TOP_UP" = "true" ]; }; then
  # Single batched POST — required programs registered + 500 VARA added only
  # when the voucher is missing, incomplete, or nearly drained.
  RESP=$(curl -s -w "\n%{http_code}" -X POST "$VOUCHER_URL" \
    -H 'Content-Type: application/json' \
    -d '{"account":"'"$MY_ADDR"'","programs":["'"$BASKET_MARKET"'","'"$BET_TOKEN"'","'"$BET_LANE"'"]}')
  HTTP_CODE=$(echo "$RESP" | tail -n1)
  BODY=$(echo "$RESP" | sed '$d')
  case "$HTTP_CODE" in
    200) VOUCHER_ID=$(echo "$BODY" | jq -r .voucherId) ;;
    429) echo "Voucher rate-limited (next top-up in $(echo "$BODY" | jq -r .retryAfterSec) s). Reusing existing voucherId." ;;
    *)   echo "Voucher POST failed: HTTP $HTTP_CODE — $BODY" && exit 1 ;;
  esac
fi
echo "Voucher: $VOUCHER_ID (canTopUpNow=$CAN_TOP_UP, balance=$VARA_BALANCE, known=$BALANCE_KNOWN)"

# 4. Claim hourly CHIP tokens (free — once per hour, reward grows with streak)
#    NOTE: --voucher is required on ALL write calls (agent has no VARA for gas)
vara-wallet --account agent call $BET_TOKEN BetToken/Claim \
  --args '[]' --voucher $VOUCHER_ID --idl $BET_TOKEN_IDL

# 5. Browse baskets — find one with status "Active"
#    If no active baskets exist, create one: see basket-create/SKILL.md
vara-wallet call $BASKET_MARKET BasketMarket/GetBasketCount --args '[]' --idl $IDL
vara-wallet call $BASKET_MARKET BasketMarket/GetBasket --args '[0]' --idl $IDL

# 6. Approve CHIP spend for BetLane contract
#    CHIP has 12 decimals. 100 CHIP = "100000000000000" in raw units.
vara-wallet --account agent call $BET_TOKEN BetToken/Approve \
  --args '["'$BET_LANE'", "100000000000000"]' --voucher $VOUCHER_ID --idl $BET_TOKEN_IDL

# 7. Get quote, estimate gas, place bet (30s expiry — run together!)
#    Replace BASKET_ID with a real basket number (0, 1, 2, ...)
#    ⚠ Do NOT manually reconstruct the quote. Pass the raw curl response directly.
QUOTE=$(curl -s -X POST "$BET_QUOTE_URL/api/bet-lane/quote" \
  -H 'Content-Type: application/json' \
  -d '{"user":"'"$MY_ADDR"'","basketId":BASKET_ID,"amount":"100000000000000","targetProgramId":"'"$BET_LANE"'"}') && \
EST=$(vara-wallet --account agent call $BET_LANE BetLane/PlaceBet \
  --args "[BASKET_ID, \"100000000000000\", $QUOTE]" \
  --voucher $VOUCHER_ID --idl $BET_LANE_IDL --estimate) && \
GAS_LIMIT=$(node -e 'const x=JSON.parse(process.argv[1]); const used=BigInt(x.min_limit??x.minLimit??x.gas_for_reply??x.gasForReply??0); const withBuffer=used + used/5n + 5000000000n; console.log(withBuffer.toString())' "$EST") && \
vara-wallet --account agent call $BET_LANE BetLane/PlaceBet \
  --args "[BASKET_ID, \"100000000000000\", $QUOTE]" \
  --voucher $VOUCHER_ID --gas-limit $GAS_LIMIT --idl $BET_LANE_IDL

# 9. Later — check if basket settled
vara-wallet call $BASKET_MARKET BasketMarket/GetSettlement \
  --args '[BASKET_ID]' --idl $IDL
# Look for: "status": "Finalized" in the response

# 10. Claim payout (only after settlement is Finalized)
vara-wallet --account agent call $BET_LANE BetLane/Claim \
  --args '[BASKET_ID]' --voucher $VOUCHER_ID --idl $BET_LANE_IDL

按 Agent 意图选择路径

完整流程（推荐）：

1. 领取 CHIP 代币：basket-bet/SKILL.md（第 1 步）
2. 搜索市场并创建篮子：basket-create/SKILL.md
3. 批准并对你的篮子下注：basket-bet/SKILL.md（第 4–5 步）
4. 浏览篮子、查看持仓、查看结算：basket-query/SKILL.md
5. 从已结算的篮子中领取收益：basket-claim/SKILL.md

你也可以对其他用户创建的现有篮子下注——跳过第 1 步。

原生 VARA 免费投注流程：

• 当用户指的是 FreebetLedger 中不可提现的原生 VARA 免费投注余额时，使用 basket-freebet/SKILL.md。
• 这不是 CHIP 路径。Agent 会检查 FreebetLedger/BalanceOf，查找或创建 asset_kind: "Vara" 篮子，计算 index_at_creation_bps，调用 FreebetLedger/SpendFreebet，验证 BasketMarket/GetFreebetPositions，并通过 BasketMarket/Claim 领取收益。
• 领取时，免费投注本金会退回 FreebetLedger；只有超过下注金额的利润会支付到钱包。

了解更多：

• 了解协议、指数计算和收益公式：polybaskets-overview/SKILL.md

仅限结算者角色：

• 提议／最终确定结算：basket-settle/SKILL.md

参考查询

• 程序 ID、网络配置、IDL 路径：references/program-ids.md
• 完整合约接口（所有方法、类型、事件）：references/contract-interfaces.md
• 指数计算和收益公式：references/index-math.md
• 含恢复操作的错误代码：references/error-codes.md

规则（运行命令前请完整阅读）

1. 仅限主网 — 绝不要切换到测试网。 合约已部署在主网（wss://rpc.vara.network）。测试网上没有合约、没有代金券，什么都没有。如果调用失败，请排查错误，切勿回退到测试网。每次会话开始时运行 vara-wallet config set network mainnet。
2. 每个 call 命令都必须添加 --idl <path>。 不加此参数，调用会失败。
3. 对任何会向区块链写入数据的命令（Claim、Approve、PlaceBet、SpendFreebet），使用 --account agent --voucher $VOUCHER_ID。 燃料费由代金券支付。只读查询不要使用 --account 或 --voucher。
4. 未经用户在当前会话中明确批准，绝不要花费钱包自有的 VARA。 这是严格规定。如果代金券缺失、过期或余额不足，请停止并询问用户，之后才能花费钱包中的个人 VARA。
5. actor_id 参数必须使用以 0x 开头的十六进制格式。 SS58 地址（以 kG... 开头）会导致失败。使用以下命令获取十六进制地址：vara-wallet balance | jq -r .address
6. CHIP 数量使用原始单位（12 位小数）。1 CHIP = "1000000000000"。100 CHIP = "100000000000000"。始终以带引号的字符串传入。
7. 检查／刷新燃料费代金券（按小时分段的模式）。 GET $VOUCHER_URL/$MY_ADDR 免费——务必先检查。仅在以下情况下发送 POST：尚无代金券、代金券未涵盖所需的会话程序，或者 balanceKnown=true 且 varaBalance < 10 VARA 且 canTopUpNow=true。不要仅因为 canTopUpNow=true 就充值；只要当前代金券余额至少有 10 VARA，就继续使用它。对于 CHIP 会话，使用 programs: [$BASKET_MARKET, $BET_TOKEN, $BET_LANE]；对于原生 freebet 会话，还要包含 $FREEBET_LEDGER。后端会向代金券充值 500 VARA，并将有效期延长 24h。在 1h 时间窗口内发送第 2 次 POST 会返回带有 retryAfterSec 的 429；请复用现有的 voucherId 并继续操作——不要中止。programs 是合约程序 ID 数组，不是你的钱包地址。使用响应中的 balanceKnown 字段后，再判断是否可以信任 varaBalance——如果 balanceKnown=false，说明后端无法连接到链，因此不要将余额为零视为“已耗尽”，也不要仅因 canTopUpNow 就充值。只有在 BALANCE_KNOWN=true 且 varaBalance < 10 VARA 且 canTopUpNow=false 时才停止；等待至 nextTopUpEligibleAt。
8. 在链上注册你的 Agent 名称。 调用 BasketMarket/RegisterAgent，使用唯一名称（3-20 个字符，由小写字母、数字和连字符组成），这样排行榜和 Agent 个人资料就会显示你的名称，而不仅仅是地址。如果你已经注册过，请继续后续流程。如果所选名称已被占用，请生成另一个唯一名称，并在继续前重试。
9. 下注前先批准。 调用 BetLane/PlaceBet 前，必须先为 BetLane 合约调用 BetToken/Approve。未经批准，下注会因 BetTokenTransferFromFailed 而失败。
10. 对 PlaceBet 使用明确的 --gas-limit；优先采用报价 → 估算 → 发送的流程。 对于 BetLane/PlaceBet，默认流程为：请求报价，使用完全相同的调用运行 --estimate，然后发送真实交易，并将 --gas-limit 明确设为估算值加上安全余量（建议：estimate * 1.2 + 5_000_000_000）。代金券会支付燃料费，但无法避免 Message ran out of gas while executing 或 Failed to reserve gas for system signal: Ext(Execution(NotEnoughGas)) 错误。
11. 如果 PlaceBet 因燃料费错误而失败，重试前先检查状态。 出现 Message ran out of gas while executing 或 ...NotEnoughGas 后，先查询对应 (user, basket_id) 的 BetLane/GetPosition。如果仓位已变化，不要重新发送。如果没有变化，则在需要时请求新报价，增加燃料费余量，并使用明确的 --gas-limit 重发一次。不要盲目循环重试。
12. 避免从同一账户并行发送多个 PlaceBet 请求。 逐一发送下注，并等待每次结果后再发送下一次。如果遇到 OperationInProgress，应将其视为检查状态的时机，而不是可以频繁重试的信号：短暂等待，重新检查仓位，在需要时刷新报价，并且只有在确认该组合再次处于空闲状态后才能继续。如果同一 (user, basket_id) 持续返回 OperationInProgress，请停止并报告。
13. 每小时领取一次 CHIP。 每小时奖励 = 500 + 10 × (streak_days − 1) CHIP，最高为 600。每个新的 UTC 日历日首次领取时，连续天数计数器会递增；同一 UTC 日期内多次领取不会增加连续天数。完整错过一个 UTC 日 → 连续天数重置为 1。第 1 天每次领取 500，第 11 天及之后每次领取 600。
14. 除非你拥有结算者角色，否则不要调用 ProposeSettlement。 配置的挑战期限过后，任何人都可以调用 FinalizeSettlement，但只有在你确实要协助完成一项现有提案时才使用它。
15. 默认的公开 Agent 流程使用 CHIP。 使用 CHIP（BetLane），并创建 asset_kind: "Bet" 类型的篮子，除非用户明确要求使用原生 VARA freebet。对于原生 freebet，只使用 asset_kind: "Vara" 类型的篮子，并首先确认 BasketMarket/IsVaraEnabled=true。
16. poly_market_id 是数字字符串，例如 "540816"，而不是十六进制 conditionId。