openfunderse-participant

name	openfunderse-participant
description	Participant MoltBot for allocation proposal, validation, and submission
metadata	{"openclaw":{"installCommand":"npx @wiimdy/openfunderse@2.0.0 install openfunderse-participant --with-runtime","requires":{"env":["RELAYER_URL","PARTICIPANT_PRIVATE_KEY","BOT_ID","CHAIN_ID","RPC_URL","PARTICIPANT_ADDRESS","PARTICIPANT_AUTO_SUBMIT","PARTICIPANT_REQUIRE_EXPLICIT_SUBMIT","PARTICIPANT_TRUSTED_RELAYER_HOSTS","PARTICIPANT_ALLOW_HTTP_RELAYER"],"bins":["node","npm"]},"primaryEnv":"PARTICIPANT_PRIVATE_KEY","skillKey":"participant"}}

Participant MoltBot Skill

Participant role proposes and validates AllocationClaimV1 only.

Security / Consent Notes (Read First)

• Installing via npx @wiimdy/openfunderse@2.0.0 ... executes code fetched from npm. Prefer pinning a known version (as shown) and reviewing the package source before running in production.
• PARTICIPANT_PRIVATE_KEY is highly sensitive. Use a dedicated wallet key for this bot; never reuse treasury/admin keys.
• bot-init is a destructive rotation tool: it generates a fresh wallet, updates .env.participant, and stores wallet backups under ~/.openclaw/workspace/openfunderse/wallets.
• By default, install and bot-init also sync env vars into ~/.openclaw/openclaw.json and bot-init runs openclaw gateway restart. This mutates global OpenClaw runtime state and can affect other skills.
  • Use --no-sync-openclaw-env for file-only behavior.
  • Use --no-restart-openclaw-gateway to avoid restarting the gateway.
  • Before mutating global config, back up ~/.openclaw/openclaw.json.

Quick Start

1. Install (pick one). You do not need to run both:

Manual (direct installer; run in a Node project dir, or npm init -y first):

npm init -y && npx @wiimdy/openfunderse@2.0.0 install openfunderse-participant --with-runtime

ClawHub:

npx clawhub@latest install openfunderse-participant

2. Optional: create or rotate a dedicated participant signer key.

If you already have a key, set PARTICIPANT_PRIVATE_KEY and PARTICIPANT_ADDRESS directly in OpenClaw env (/home/ubuntu/.openclaw/openclaw.json -> env.vars) or in ~/.openclaw/workspace/.env.participant. You do not need to run bot-init.

If you want the installer to generate a new wallet and write it into the role env file:

npx @wiimdy/openfunderse@2.0.0 bot-init \
  --skill-name participant \
  --yes \
  --no-restart-openclaw-gateway

bot-init updates an existing .env.participant.
If the env file is missing, run install first (without --no-init-env) or pass --env-path. If PARTICIPANT_PRIVATE_KEY is already set (not a placeholder), re-run with --force to rotate.

Environment Source of Truth (Hard Rule)

• In OpenClaw runtime on Ubuntu, treat /home/ubuntu/.openclaw/openclaw.json (env.vars) as the canonical env source.
• Do not require manual .env sourcing for normal skill execution.
• If .env* and openclaw.json disagree, use openclaw.json values.
• When user asks env setup, direct them to update openclaw.json first.

3. Optional local shell export (debug only):

set -a; source ~/.openclaw/workspace/.env.participant; set +a

This step is not required for normal OpenClaw skill execution.

Telegram slash commands:

Note: Telegram integration is handled by your OpenClaw gateway. This pack does not require a Telegram bot token; configure Telegram credentials at the gateway layer.

/allocation --fund-id <id> --epoch-id <n> --target-weights <w1,w2,...> [--verify] [--submit]
/allocation --claim-file <path> [--verify] [--submit]
/join --room-id <id>
/deposit --amount <wei> [--vault-address <0x...>] [--native] [--submit]
/withdraw --amount <wei> [--vault-address <0x...>] [--native] [--submit]
/redeem --shares <wei> [--vault-address <0x...>] [--submit]
/vault_info [--vault-address <0x...>] [--account <0x...>]
/participant_daemon --fund-id <id> --strategy <A|B|C> [--interval-sec <n>] [--epoch-source <relayer|fixed>] [--epoch-id <n>] [--submit]

Notes:

• allocation will auto-validate on submit (--submit implies verify).
• submit_allocation (legacy) validates the claim hash first; without --submit it is validation-only dry-run.

BotFather /setcommands (copy-paste ready):

start - Show quick start
help - Show command help
allocation - Mine (optional verify) and optionally submit allocation claim
join - Register this bot as a participant for the fund mapped to the room id
deposit - Deposit native MON or ERC-20 into vault
withdraw - Withdraw assets from vault (native or ERC-20)
redeem - Burn vault shares and receive assets
vault_info - Show vault status and user PnL
participant_daemon - Run participant allocation daemon

Notes:

• Slash parser accepts underscores, so /participant_daemon equals /participant-daemon.
• key=value style is also accepted (fund_id=demo-fund).
• On first install, register these commands in Telegram via @BotFather -> /setcommands.

OpenClaw note:

• install / bot-init sync env keys into ~/.openclaw/openclaw.json (env.vars) by default.
• bot-init also runs openclaw gateway restart after a successful env sync, so the gateway picks up updates.
• Use --no-sync-openclaw-env for file-only behavior, or --no-restart-openclaw-gateway to skip the restart.
• If env still looks stale: run openclaw gateway restart and verify values in /home/ubuntu/.openclaw/openclaw.json.

Note:

• The scaffold includes a temporary private key placeholder by default.
• Always run bot-init before funding or running production actions.
• bot-init generates a new wallet (private key + address) and writes it into the role env file.

Relayer Bot Authentication (Signature)

This skill authenticates relayer write APIs with an EIP-191 message signature (no BOT_API_KEY).

Message format:

• openfunderse:auth:<botId>:<timestamp>:<nonce>

Required headers:

• x-bot-id: BOT_ID
• x-bot-signature: <0x...>
• x-bot-timestamp: <unix seconds>
• x-bot-nonce: <uuid/random>

Relayer verifies this signature against Supabase fund_bots.bot_address.

Participant bot registration can be done by:

• Participant: POST /api/v1/rooms/{roomId}/join (recommended for Telegram groups)
• Strategy: POST /api/v1/funds/{fundId}/bots/register (direct registration)

If the participant bot is not registered for the fund, relayer will reject participant write APIs with 401/403.

propose_allocation outputs canonical allocation claim:

• claimVersion: "v1"
• fundId, epochId, participant
• targetWeights[] (integer, non-negative, sum > 0)
• horizonSec, nonce, submittedAt

No crawl/evidence/sourceRef schema is used.

Vector mapping rule:

• targetWeights[i] maps to strategy riskPolicy.allowlistTokens[i].
• Participants must submit weights in the same token order used by the strategy allowlist.

Daemon mode (auto-claim)

For MVP, the participant runtime supports an always-on daemon that:

1. reads NadFun testnet signals (quote/progress/buy logs),
2. computes targetWeights[] using a fixed allowlist order,
3. submits AllocationClaimV1 to the relayer on a timer.

Use the --strategy command flag:

• A: momentum (buy pressure)
• B: graduation proximity (progress)
• C: impact-aware (quote-based)

Submission safety gates

submit_allocation is guarded by default:

1. PARTICIPANT_REQUIRE_EXPLICIT_SUBMIT=true requires explicit submit=true.
2. PARTICIPANT_AUTO_SUBMIT=true must be enabled for network transmission.
3. RELAYER_URL host is checked by PARTICIPANT_TRUSTED_RELAYER_HOSTS when set.
4. RELAYER_URL must use https unless PARTICIPANT_ALLOW_HTTP_RELAYER=true (local development only).

If gate is closed, return decision=READY (no submit).

Input contracts

propose_allocation

{
  "taskType": "propose_allocation",
  "fundId": "string",
  "roomId": "string",
  "epochId": "number",
  "allocation": {
    "participant": "0x... optional",
    "targetWeights": ["7000", "3000"],
    "horizonSec": 3600,
    "nonce": 1739500000
  }
}

submit_allocation

Validates the claim hash first, then submits to relayer if --submit is passed. Without --submit, returns validation-only dry-run result.

{
  "taskType": "submit_allocation",
  "fundId": "string",
  "epochId": "number",
  "observation": "propose_allocation output observation",
  "submit": true
}

Rules

1. Supported Tasks Only: Use only propose_allocation, submit_allocation (validates automatically before submission).
2. Schema Rule: Claim schema is AllocationClaimV1 only (claimVersion, fundId, epochId, participant, targetWeights, horizonSec, nonce, submittedAt).
3. Weights Rule: targetWeights must be integer, non-negative, non-empty, and sum > 0.
4. Index Mapping Rule: targetWeights[i] MUST map to strategy riskPolicy.allowlistTokens[i] in the same order.
5. Scope Validation: If subject fundId/epochId differs from task scope, return FAIL.
6. Hash Validation: For CLAIM, recompute canonical hash via SDK and compare with subjectHash; mismatch returns FAIL.
7. Submit Endpoint: submit_allocation sends claim to relayer POST /api/v1/funds/{fundId}/claims.
8. No Implicit Submit: Submit only when explicit submit gate is satisfied.
9. Trusted Relayer: In production, set PARTICIPANT_TRUSTED_RELAYER_HOSTS and avoid arbitrary relayer URLs.
10. Key Hygiene: Use dedicated participant keys only; never use custody/admin keys.
11. Env Source Priority: Resolve runtime env from /home/ubuntu/.openclaw/openclaw.json (env.vars) before local .env* files.
12. Legacy Tasks Disabled: Do not use mine_claim, verify_claim_or_intent_validity, submit_mined_claim, attest_claim.