agents

Runtime entry for participant/strategy MoltBots.

ER2 quickstart:

• runbook: packages/agents/ER2_RUNBOOK.md
• env files are generated by @wiimdy/openfunderse install/bot-init flows.

Unified entrypoint:

npm run clawbot:run -w @wiimdy/openfunderse-agents -- \
  --role strategy \
  --action propose_intent \
  --fund-id demo-fund \
  --intent-file /tmp/intent.json \
  --execution-route-file /tmp/route.json

One-command smoke:

npm run bot:smoke:e2e -w @wiimdy/openfunderse-agents

Role

• Monorepo bot runtime package (execution code), not installer/distribution.
• Owns participant claim/strategy intent runtime flows used by local smoke/E2E paths.

Shared protocol utilities:

• @claw/protocol-sdk from packages/sdk

Run:

npm run dev -w @wiimdy/openfunderse-agents

Env loading defaults (no manual source required):

• strategy commands (strategy-*, clawbot-run --role strategy): .env then .env.strategy
• participant commands (participant-*, clawbot-run --role participant): .env then .env.participant
• Runtime also reads OpenClaw config env vars from ~/.openclaw/openclaw.json (env.vars) before local .env* files.
• Existing shell env values always win over OpenClaw/local file values.

Telegram slash compatibility:

• Slash commands are accepted by the runtime entrypoint.
• /propose_intent maps to clawbot-run --role strategy --action propose_intent.
• /allocation maps to clawbot-run --role participant --action allocation.
• /join maps to clawbot-run --role participant --action join.
• Underscore option style is supported for key/value args (fund_id=demo -> --fund-id demo).

Participant claim model (allocation only)

Participant claim is AllocationClaimV1:

• input: targetWeights[], horizonSec, nonce
• canonical hash: SDK buildCanonicalAllocationClaimRecord
• no crawl/source/evidence payload in v0 claim model
• mapping rule: targetWeights[i] aligns to strategy riskPolicy.allowlistTokens[i]

Claim to intent flow (v0):

• relayer aggregates participant claims into epoch aggregateWeights
• strategy reads snapshot (snapshotHash, claimCount, optional aggregateWeights)
• strategy proposes BUY/SELL intent that reduces delta between current position mix and aggregate target mix

Wave A runtime env (relayer client + signer)

Relayer client (signature auth for relayer write APIs):

• RELAYER_URL
• BOT_ID
• STRATEGY_PRIVATE_KEY (strategy role) or PARTICIPANT_PRIVATE_KEY (participant role)
• PARTICIPANT_ADDRESS (required for claim submit; must match registered participant bot address)

Signer:

• PARTICIPANT_PRIVATE_KEY
• CHAIN_ID
• INTENT_BOOK_ADDRESS (required only for intent attestation signing)

Participant submit safety:

• PARTICIPANT_AUTO_SUBMIT (false by default)
• PARTICIPANT_REQUIRE_EXPLICIT_SUBMIT (true by default)
• optional host allowlist: PARTICIPANT_TRUSTED_RELAYER_HOSTS=relayer.example.com
• local dev only: PARTICIPANT_ALLOW_HTTP_RELAYER=true

Participant optional scoped env:

• PARTICIPANT_BOT_ID, PARTICIPANT_PRIVATE_KEY, PARTICIPANT_ADDRESS
• if omitted, participant flow uses BOT_ID, PARTICIPANT_PRIVATE_KEY with PARTICIPANT_ADDRESS

Strategy signer env:

• STRATEGY_PRIVATE_KEY
• STRATEGY_ADDRESS
• STRATEGY_AUTO_SUBMIT (false by default)
• STRATEGY_REQUIRE_EXPLICIT_SUBMIT (true by default)
• optional host allowlist: STRATEGY_TRUSTED_RELAYER_HOSTS=relayer.example.com
• local dev only: STRATEGY_ALLOW_HTTP_RELAYER=true
• CLAW_FUND_FACTORY_ADDRESS
• INTENT_BOOK_ADDRESS, CLAW_CORE_ADDRESS
• NADFUN_EXECUTION_ADAPTER_ADDRESS (fallback: ADAPTER_ADDRESS)
• optional preflight: STRATEGY_CREATE_MIN_SIGNER_BALANCE_WEI

Participant commands

# Join fund by room id (recommended for Telegram group flows)
npm run participant:join -w @wiimdy/openfunderse-agents -- --room-id <room-id>

# Unified allocation (mine + optional verify + optional submit)
npm run participant:allocation -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund --epoch-id 1 --target-weights 7000,3000 --verify --submit

# Legacy (still supported):
npm run participant:propose-allocation -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund --epoch-id 1 --target-weights 7000,3000 --out-file /tmp/participant-allocation.json
npm run participant:submit-allocation -w @wiimdy/openfunderse-agents -- \
  --claim-file /tmp/participant-allocation.json --submit

Daemon mode (auto-generate weights from NadFun signals):

# strategies: A (momentum), B (progress), C (impact-aware)
npm run participant:daemon -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund \
  --strategy A \
  --interval-sec 60 \
  --epoch-source relayer \
  --submit

EC2/systemd deployment:

• packages/agents/EC2_PARTICIPANT_DAEMON.md

Slash aliases:

• /allocation
• /join
• /deposit
• /withdraw
• /redeem
• /vault_info
• /participant_daemon

Default participant safety behavior:

• PARTICIPANT_REQUIRE_EXPLICIT_SUBMIT=true and no --submit => decision: "READY" (no relayer transmission)
• --submit but PARTICIPANT_AUTO_SUBMIT=false => fail-closed with SAFETY_BLOCKED

Strategy commands (EOA signer)

# 0) Copy deploy config template and edit values
cp packages/agents/config/deploy-config.template.json /tmp/deploy-config.json

# 0) Create fund directly onchain via Factory (dry-run only)
npm run strategy:create:fund -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund-001 \
  --fund-name "Demo Fund 001" \
  --deploy-config-file /absolute/path/to/deploy-config.json

# 0-1) Submit createFund onchain + sync deployment metadata to relayer
npm run strategy:create:fund -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund-001 \
  --fund-name "Demo Fund 001" \
  --deploy-config-file /absolute/path/to/deploy-config.json \
  --telegram-room-id -1001234567890 \
  --submit

# 1) READY_FOR_ONCHAIN intent attestation submit (IntentBook.attestIntent via signer tx)
npm run strategy:attest:onchain -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund \
  --intent-hash 0x...

# 2) READY execution jobs submit (ClawCore.executeIntent via signer tx)
npm run strategy:execute:ready -w @wiimdy/openfunderse-agents -- \
  --fund-id demo-fund \
  --limit 10

# 3) Dry-run intent execution against core
npm run strategy:dry-run:intent -w @wiimdy/openfunderse-agents -- \
  --intent-hash 0x... \
  --intent-file /tmp/intent.json \
  --execution-route-file /tmp/route.json

Slash aliases:

• /propose_intent
• /dry_run_intent
• /attest_intent
• /execute_intent
• /create_fund

deploy-config.json location and schema

The repository now includes a starter template:

• packages/agents/config/deploy-config.template.json

strategy-create-fund requires one of:

• --deploy-config-file <path>
• --deploy-config-json '<json>'

Copy the template and update values:

cp packages/agents/config/deploy-config.template.json /tmp/deploy-config.json

Field guide:

• fundOwner (required): final owner of the fund.
• strategyAgent (optional): strategy bot address. if omitted, CLI fallback is --strategy-bot-address or STRATEGY_ADDRESS.
• asset (required): vault asset token (for Monad testnet usually WMON).
• vaultName / vaultSymbol (required): ERC4626 metadata.
• intentThresholdWeight (required): total verifier weight required for intent approval.
• nadfunLens (optional): NadFun lens address (0x000...0000 allowed).
• initialVerifiers + initialVerifierWeights (required together): same length, each weight must be positive.
• initialAllowedTokens (optional): allowlist for tradable tokens.
• initialAllowedAdapters (optional): allowlist for execution adapters. use your deployed NadFun adapter address.

Note:

• SnapshotBook is auto-deployed by ClawFundFactory.createFund and returned via the FundDeployed event. It is not part of the deploy config payload.

Strategy skill guarded submit

Programmatic skill path builds proposal first, then submits only when submit gates are explicitly enabled.

1. build strategy decision (proposeIntent)
2. if submit=true and STRATEGY_AUTO_SUBMIT=true, submit canonical intent to relayer (POST /intents/propose)
3. if step 2 passed, send onchain IntentBook.proposeIntent via strategy signer tx

import { proposeIntentAndSubmit } from '@wiimdy/openfunderse-agents';

const out = await proposeIntentAndSubmit({
  taskType: 'propose_intent',
  fundId: 'demo-fund',
  roomId: '-1001234567890',
  epochId: 12,
  snapshot: {
    snapshotHash: '0x...',
    finalized: true,
    claimCount: 6
  },
  marketState: {
    network: 10143,
    nadfunCurveState: {},
    liquidity: {},
    volatility: {}
  },
  riskPolicy: {
    maxNotional: '1000000000000000000',
    maxSlippageBps: 500,
    allowlistTokens: ['0x...'],
    allowlistVenues: ['nadfun']
  },
  submit: true
});

Default safety behavior:

• STRATEGY_REQUIRE_EXPLICIT_SUBMIT=true and no submit => returns decision: "READY" (no relayer/onchain submission)
• submit: true but STRATEGY_AUTO_SUBMIT=false => throws fail-closed error

Implemented modules:

• /Users/wiimdy/agent/packages/agents/src/lib/relayer-client.ts
• /Users/wiimdy/agent/packages/agents/src/lib/signer.ts

Install-pack canonical source

Target onboarding UX:

npx @wiimdy/openfunderse@latest install openfunderse-strategy --with-runtime
npx @wiimdy/openfunderse@latest install openfunderse-participant --with-runtime

Canonical pack files are maintained at:

• packages/openfunderse/packs/openfunderse-strategy/config/setup-manifest.json
• packages/openfunderse/packs/openfunderse-strategy/openfunderse-strategy/SKILL.md
• packages/openfunderse/packs/openfunderse-participant/config/setup-manifest.json
• packages/openfunderse/packs/openfunderse-participant/openfunderse-participant/SKILL.md

packages/agents keeps runtime code only (src/*, dist/*).

Prompt references:

• See skill packs in packages/openfunderse/packs/