Scenario Engine

Demo

About

This is an open-source improvement to hedera-dev/hedera-harness, the CLI that drives a coding agent to build Hedera apps and then decides whether the work passed. The harness already had CHAIN: one throwaway testnet wallet injected into the generated app. That is the wrong layer for two-party transfers, HTS airdrops, or HCS messages. People were left hoping Playwright clicked Transfer, or trusting a toast after the agent wrote 40 to 80 lines of SDK boilerplate. A toast is not proof. The agent does not get to grade itself. This project adds SCENARIO, an opt-in fifth stage. You write a short YAML plan with named actors (alice, bob), steps (transfer HBAR, create a token, associate, airdrop, create an HCS topic, submit a message), and asserts. The harness funds those actors from your testnet operator, sends real transactions with the official @hiero-ledger/sdk, then polls the public testnet mirror until the effects are visible: Bob's HBAR, Bob's token balance, the topic text. The coding agent does not run this and does not declare success. Stage order is GENERATE, ASSERT, SCENARIO, SMOKE, EVALUATE. A failed native plan skips the browser, so you do not pay for Playwright when the chain work already failed. A mirror or SDK outage is treated as infrastructure, not as an app failure. There is also hedera-harness validate-scenario, which runs the plan alone with no agent. That is the demo path. Testnet only. Mainnet is rejected. Actor keys are never committed.

How it's made

Built in TypeScript on top of hedera-harness 2.0 (schema v3, their dev branch). The new code lives in src/scenario/: a YAML plan parser, operator env reuse from chainValidation, real AccountCreate / AccountDelete for named actors, an executor that uses the @hiero-ledger/sdk already shipped with the CLI, and a small REST client that polls https://testnet.mirrornode.hedera.com for HBAR balances, token balances, topic messages, and pending airdrops. Steps map to real SDK transactions: TransferTransaction, TokenCreateTransaction, TokenAssociateTransaction, TokenAirdropTransaction, TokenClaimAirdropTransaction (PendingAirdropId built from the mirror, not a fake fromString), TopicCreateTransaction, TopicMessageSubmitTransaction. Later steps can refer to earlier ones by id (token: gold, topic: chat). The stage is wired into attemptStages so it runs after ASSERT and before SMOKE. sessionRunner provisions actors once per run and sweeps leftover HBAR at the end (best effort: a token treasury cannot be deleted). doctor checks operator env and plan shape. CLI help and validate-scenario call the same executor as a full run. harnessGit treats scenario-actors.json as a secret. No in-process fake ledger. No simulated consensus. Tests cover plan parsing, recipe load (inline and file:), mainnet rejection, CLI wiring, and cleanup of actor keys. Docs are in docs/scenarios.md plus the README stage table. The skeleton ships a two-actor HBAR / HTS / HCS example.