Wave Creator Workflows: Projects, Bots, Names and AI Recipes

Wave Creator Workflows: Projects, Bots, Names and AI Recipes

TutorialWave OS TeamOct 18, 2026 13 min read
#Wave Web#Bots#TNS#BrainVault#AI Recipes

Wave Creator Workflows: Consumer and Developer Guide

This document describes the workflows for creating, minting, publishing, and accessing knowledge projects and AI bots in the Wave ecosystem. All steps follow the official specifications for Wave Web (web.oswave.io) and Wave OS (app.oswave.io).


1. System Architecture Overview

The Wave ecosystem connects web interfaces, shared publishing logic, wallet signing security, permanent on-chain storage, and domain name resolution.

System Architecture Chart

System overview: how Wave Web, Wave OS, the shared Publish Bot wizard, wallets, BrainVault v3 and TNS connect. · Tap to enlarge

Core Components

  1. Wave Web (web.oswave.io): When logged out, Wave Web operates as a read-only browser over BrainVault cards. When logged in, it acts as the Project Builder for writing cards, generating HTML pages, estimating mint costs, and publishing projects to the store. Wave Web never holds private keys, seed phrases, or handling wallet funds directly.
  2. Wave OS (app.oswave.io): Wave OS hosts the Bot Designer, Mascot Editor, Rules Configurator, and Bot Store interface. Official Wave bots are signed by the official Wave OS signer (0x4e96028447b653e43ff359aaff9f79c0479386db).
  3. Shared Publish Bot Wizard: Both Wave Web and Wave OS import the exact same Publish Bot wizard module. This ensures identical UI steps, preflight checks, error messages, and TFUEL cost calculations across both platforms.
  4. User External Wallet: All minting and domain configuration actions require external user signatures from the Wave Wallet mobile app or MetaMask.
  5. Theta Mainnet (Chain 361): BrainVault v3 smart contract (0xDb8230f5a2859fca29e0ae6c8521784c1a34dc90) stores immutable text cards, avatar designs, bot rules, and listing manifests. Cards are capped at 4 KB per card.
  6. Theta Name Service (TNS): The public TNS resolver (0x428101CB7a0D22587a6f098A518c36Af2a1b2E31) maps readable domain names (such as wave.theta) to bots using the text record wave.bot set to v3:<listing id>. Standard routes include the store index web.oswave.io/tns/bots.theta, individual bot pages /tns/bots.theta/<slug>, name resolution pages /tns/<name>.theta, and <slug>.bots.theta redirects to the bot page.

2. Workflow A: Create and Publish a Project (Wave Web)

Workflow A covers intake of knowledge sources, card splitting, cost estimation, batch minting to Theta chain 361, and store listing inside Wave Web (web.oswave.io).

Workflow A Chart

Workflow A: create and publish a project in Wave Web, from content intake to store listing. · Tap to enlarge

Step-by-Step Procedure

  1. Intake Content: The creator submits content into Wave Web via file drag and drop (markdown, PDF, text), pasting raw text or URLs, or asking the Wave AI Assistant to draft content.
  2. Filter and Split Content: Wave Web filters out sensitive PII (emails, phone numbers) and blocks secret material (private keys, seed phrases, API keys). Content is automatically split into readable chunks under 2,500 bytes per card.
  3. Assemble and Preview: The creator organizes cards into project sections or generates custom HTML and CSS pages. Interactive previews render across mobile, tablet, and desktop viewports.
  4. Calculate TFUEL Cost: Wave Web measures each card's exact size and shows the total minting cost before anything is signed. On BrainVault v3 a full 2.5 KB card costs about 1.7 TFUEL, and small cards cost less (roughly 1 TFUEL).
  5. Connect Wallet: The creator connects an external wallet (Wave Wallet mobile app or MetaMask). Wave Web compares the estimated cost against the connected wallet balance.
  6. Batch Mint in Waves: The creator approves batch minting transactions in their wallet. Cards are written permanently to BrainVault v3 contract 0xDb8230f5a2859fca29e0ae6c8521784c1a34dc90.
  7. Post-Mint Read-Back Verification: System calls waveApi?action=check&ref=v3:<id> to verify on-chain card registration, content hash matching, and accessibility.
  8. Publish to Store: The project is listed in the Wave Web Store index (web.oswave.io/tns/bots.theta).

Operational Summary

  • Who Does What: Creator drafts and previews content in Wave Web. Creator wallet signs transactions and pays gas. Wave Web validates, estimates, and indexes cards.
  • What It Costs: Approximately 1.7 TFUEL per 2.5 KB card. Re-minting identical cards costs 0 TFUEL due to content sha256 deduplication.
  • Common Errors and Fixes:
    • Error: Card size exceeds 4 KB cap. Fix: Enable automatic card splitting or reduce individual card character count below 2,500 bytes.
    • Error: Wallet balance short by X TFUEL. Fix: Transfer additional TFUEL into the connected wallet address before initiating batch minting.
    • Error: Rejected due to detected API key. Fix: Remove hardcoded secrets from text cards before proceeding to preflight validation.

3. Workflow B: Publish a Bot with the 6-Step Wizard

Workflow B details the unified 6-step Publish Bot wizard shared by Wave OS and Wave Web.

Workflow B Chart

Workflow B: the 6-step Publish Bot wizard, from review to live check. · Tap to enlarge

Step-by-Step Procedure

  1. Step 1: Review: Displays mascot preview, bot name, slug, pitch description, rules summary, and knowledge card count. Default values fill empty fields: 5 free questions daily, minimum paid answer price of 0.27 TFUEL total (0.15 AI cost, 0.12 owner fee, 2% Wave fee), and always open hours.
  2. Step 2: Preflight Checks: System validates schemas without triggering wallet prompts:
    • Design: Avatar card wave.avatar/1 must have kind pixel20. Base64 pixel string must decode to exactly 400 indices, all within palette limits.
    • Rules: Valid wave.rules/1 structure. Paid answer calculation (owner fee + AI cost) * 1.02 >= 0.27 TFUEL. Away message 280 characters or fewer.
    • Listing: NAME and SLUG present. Slug formatted as lowercase alphanumeric characters and hyphens. rulesHash matches sha256 of rules card content.
    • Refs & Security: Card references use normalized format vN:id (for example v3:6). Cards fit 4 KB limit. Zero private secrets detected.
    • Name Check: Queries owner of selected .theta name on chain. If connected wallet does not match, displays notice: <name> is owned by 0x1234...abcd. Connect that wallet to point it at this bot, or skip this step. (This notice does not block card minting).
  3. Step 3: Cost Calculation: Itemizes total TFUEL costs for design, rules, listing, new knowledge cards, and name pointing gas. Cards with identical content sha256 are reused without re-minting. Displays wallet balance and Enough or Short by X TFUEL.
  4. Step 4: Progressive Signing: Guides creator through ordered wallet prompts: Design Card -> Rules Card -> Listing Card -> TNS Name Record. Progress bar displays Signature X of Y. If tab closes or transaction drops, state saves automatically. Reopening wizard resumes at the next unsigned item without duplicate minting.
  5. Step 5: Point .theta Name: Executes setText(namehash("<name>.theta"), "wave.bot", "v3:<listing_id>") on TNS public resolver 0x428101CB7a0D22587a6f098A518c36Af2a1b2E31, signed by the name owner wallet.
  6. Step 6: Live Check: Polls https://web.oswave.io/functions/waveApi?action=check&ref=v3:<listing_id>&name=<name>.theta every 10 seconds for up to 5 minutes. Displays LIVE with links to store page /tns/bots.theta/<slug> and name page /tns/<name>.theta, or Minted, not live: <reason> with a Check again button.

Operational Summary

  • Who Does What: Creator configures bot details and signs wallet prompts. Shared wizard module validates schema, calculates costs, manages signing state, and polls live status.
  • What It Costs: About 4 TFUEL for a complete new bot (mascot design card about 1.7 TFUEL, rules and listing cards about 1 TFUEL each, plus about 0.25 TFUEL to point the name), plus about 1.7 TFUEL per 2.5 KB of new knowledge. The wizard always shows the exact total first.
  • Common Errors and Fixes:
    • Error: Mascot pixels decode to 350 values. Fix: Ensure mascot grid contains exactly 400 pixel color indices for a 20x20 canvas.
    • Error: Minimum paid answer is 0.27 TFUEL. Fix: Increase combined AI cost and creator fee so total answer price equals at least 0.27 TFUEL.
    • Error: Bare number ref '6' rejected. Fix: Convert legacy bare numbers to normalized format v3:6.

4. Workflow C: Point an Existing Bot at a .theta Name

Workflow C allows pointing a previously minted bot (for example Wavey v3:6 on wave.theta) at a .theta name independently of the main creation wizard.

Workflow C Chart

Workflow C: point an existing bot at a .theta name. · Tap to enlarge

Step-by-Step Procedure

  1. Open Bot Page: The creator opens any existing bot page in the bot application.
  2. Enter .theta Name: The creator types the target .theta name into the Point a name at this bot section.
  3. Verify Ownership: The application queries the TNS resolver contract for the registered owner of the .theta name. If the connected wallet address does not match the owner, a notice displays the owner address and prompts the user to switch wallets or skip.
  4. Sign TNS Record Update: The connected name owner wallet prompts the user to approve a transaction executing setText(node, "wave.bot", "v3:<listing_id>") on TNS public resolver 0x428101CB7a0D22587a6f098A518c36Af2a1b2E31.
  5. Poll Live Check: The system calls waveApi?action=check&ref=v3:<listing_id>&name=<name>.theta to confirm record propagation.
  6. Confirmation: Upon verification, the page displays a green LIVE badge with a link to https://web.oswave.io/tns/<name>.theta.

Operational Summary

  • Who Does What: Name owner enters name and signs TNS text record transaction in their external wallet. Application verifies ownership and polls status.
  • What It Costs: Standard Theta transaction gas fee (less than 0.1 TFUEL).
  • Common Errors and Fixes:
    • Error: Name owned by 0x1234...abcd. Fix: Switch external wallet active account to matching owner address 0x1234...abcd.
    • Error: TNS record points to bare address. Fix: TNS bot resolution uses text record wave.bot = v3:<listing_id>. Do not set addr record for bot linking.

5. Workflow D: AI Agent Path (Recipe, Dry Run, Single Approval)

Workflow D enables AI agents to construct complete bot definitions, submit a wave.botrecipe/1 payload, perform a dry run cost estimate, and request single-click human approval.

Workflow D Chart

Workflow D: the AI recipe path, with a dry run and a single human approval. · Tap to enlarge

Step-by-Step Procedure

  1. Import Recipe: The system ingests a wave.botrecipe/1 JSON recipe via the Import recipe UI button or via URL query parameter ?recipe=<url_to_json>.
  2. Parse Recipe Payload: System loads bot name, slug, pitch, category, tags, target .theta name, design object (wave.avatar/1), rules object (wave.rules/1), and knowledge array (containing existing v3:id refs or new card text objects).
  3. Preflight Validation and Dry Run: The Check only dry run mode executes Steps 1 through 3 of the wizard without opening a wallet. It validates all schemas and calculates exact itemized TFUEL costs.
  4. Display Approval Card: The wizard presents a single human review card displaying complete bot specs, mascot preview, rules breakdown, and total TFUEL cost.
  5. Human Approval: The creator reviews the generated bot spec and clicks Approve & Sign.
  6. Sequential Wallet Signing: The wizard prompts the creator through sequential wallet signatures (Design, Rules, Listing, Name).
  7. Verification and Activation: System polls waveApi?action=check until status reaches LIVE.

Operational Summary

  • Who Does What: AI agent generates wave.botrecipe/1 payload. Shared wizard executes preflight checks and dry run estimation. Human user reviews preview card and signs wallet prompts.
  • What It Costs: Same standard TFUEL minting costs calculated during dry run phase.
  • Common Errors and Fixes:
    • Error: Invalid recipe schema version. Fix: Ensure recipe JSON includes "schema": "wave.botrecipe/1".
    • Error: Remote recipe URL returns 404 or CORS error. Fix: Serve recipe JSON from a CORS-enabled endpoint or upload file directly via button.

6. Workflow E: How a Visitor Reaches a Bot

Workflow E illustrates how a visitor resolves a .theta name or store slug, loads verified BrainVault v3 cards, and interacts with the bot under free and paid quotas.

Workflow E Chart

Workflow E: how a visitor reaches a bot and asks it questions. · Tap to enlarge

Step-by-Step Procedure

  1. Visitor Opens Page: Visitor navigates to web.oswave.io/tns/<name>.theta or web.oswave.io/tns/bots.theta/<slug>.
  2. TNS Name Lookup: System queries public TNS resolver 0x428101CB7a0D22587a6f098A518c36Af2a1b2E31 for text record wave.bot, returning listing card pointer v3:<listing_id> (for example v3:6).
  3. Fetch Listing Card: System reads text card v3:6 starting with WAVE BOT LISTING, extracting bot name, slug, pitch, category, tags, creator payout, avatarRef (e.g. v3:5), and rulesHash.
  4. Fetch Avatar Card: System reads design card v3:5 (wave.avatar/1 JSON) and decodes base64 pixel string into animated 20x20 grid.
  5. Fetch Rules Card: System reads rules card (wave.rules/1 JSON) and verifies that its computed sha256 hash equals rulesHash in listing card. Loads daily free allowance (default 5 questions/day) and pricing rules.
  6. Fetch Knowledge Cards: System retrieves all referenced knowledge text cards from BrainVault v3 contract 0xDb8230f5a2859fca29e0ae6c8521784c1a34dc90.
  7. Open Bot Chat: Interface presents live chat window.
  8. Process User Questions:
    • Within Free Allowance (<= 5 questions/day): AI processes query, cites source card IDs in response, and displays verification receipt.
    • Exceeds Free Allowance (> 5 questions/day): Interface prompts user to approve TFUEL micropayment (minimum 0.27 TFUEL per answer) via connected wallet or credits balance.

Operational Summary

  • Who Does What: Visitor browses store and asks questions. Client application fetches and verifies on-chain cards. AI engine streams answers citing card references.
  • What It Costs: First 5 questions daily are free. Subsequent answers cost minimum 0.27 TFUEL per question.
  • Common Errors and Fixes:
    • Error: rulesHash mismatch. Fix: Re-mint listing card with sha256 hash matching updated rules card.
    • Error: Bot offline due to hours schedule. Fix: Display away message configured in rules card.

7. Glossary of Card Types and Reference Formats

Every card stored on BrainVault v3 must follow exact specifications and schemas. Provenance metadata must always reside inside a top-level source JSON field, never as trailer text.

Card Reference Format (vN:id)

  • All card references must strictly use the normalized vN:id format (for example v3:6 or v3:53).
  • Bare numbers (such as 6) are legacy references and are rejected by preflight validators.

1. Mascot Design Card (wave.avatar/1, e.g., v3:5)

  • Format: JSON object.
  • Schema:
{
  "schema": "wave.avatar/1",
  "kind": "pixel20",
  "palette": ["#0f172a", "#ffffff", "#22d3ee", "#8b5cf6"],
  "pixels": "<base64 encoded string of 400 palette indices>",
  "source": { "app": "wave-os" }
}
  • Rules: kind must equal pixel20. Base64 pixel string decodes to exactly 400 color indices (20x20 grid). Every index must exist in the palette array.

2. Bot Listing Card (bots:listing, e.g., v3:6)

  • Format: Structured Plain Text starting with WAVE BOT LISTING.
  • Example Payload:
WAVE BOT LISTING
NAME: Wavey
SLUG: wavey
PITCH: Wave OS assistant
CATEGORY: wave
TAGS: bot:wave-guide, wave-guide:bots, wave-guide:tns
PRICE TFUEL: 0
PUBLISHED BY: wave.theta
  • Rules: Must contain NAME and SLUG lines. Slug allows lowercase letters, numbers, and hyphens. Refers to rulesHash and avatarRef.

3. Bot Rules Card (wave.rules/1, minted at publish)

  • Format: JSON object.
  • Schema:
{
  "schema": "wave.rules/1",
  "mode": "public",
  "feeTfuel": 0.12,
  "aiCostTfuel": 0.15,
  "waveFeePct": 2,
  "minAnswerTfuel": 0.27,
  "freePerUserPerDay": 5,
  "maxPerUserPerDay": 100,
  "payout": "0xcb20457aeb7ad30dbae281efbfd7c48137db1894",
  "currency": "TFUEL",
  "hours": {
    "tz": "UTC",
    "days": [0, 1, 2, 3, 4, 5, 6],
    "start": "00:00",
    "end": "23:59",
    "alwaysOpen": true
  },
  "awayMessage": "Bot is currently offline.",
  "source": { "app": "wave-os" }
}
  • Rules: Paid total (feeTfuel + aiCostTfuel) * 1.02 must equal at least 0.27 TFUEL. Away message maximum 280 characters.

4. On-Chain Model Manifest Card (wave.model/1, e.g., v3:53)

  • Format: JSON object.
  • What it holds: the model's name, its contract address on Theta (chain 361), how to call it, and its test vectors, so anyone can check the model gives the published results.
  • Live example: Wave Genesis v1, manifest card v3:53, contract 0xfe33d2b4279ec269f4beca499c7a7b704ab54397.
  • Trust: model cards are trusted by their creator (the signer), never by the author label.

5. AI Bot Recipe (wave.botrecipe/1)

  • Format: JSON object.
  • Schema:
{
  "schema": "wave.botrecipe/1",
  "name": "Wavey",
  "slug": "wavey",
  "pitch": "Your interactive guide to Theta network.",
  "category": "Education",
  "tags": ["theta", "assistant"],
  "name_to_point": "wave.theta",
  "design": {
    "schema": "wave.avatar/1",
    "kind": "pixel20",
    "palette": ["#0f172a", "#ffffff", "#22d3ee", "#8b5cf6"],
    "pixels": "<base64 encoded string of 400 palette indices>"
  },
  "rules": {
    "schema": "wave.rules/1",
    "mode": "public",
    "feeTfuel": 0.12,
    "aiCostTfuel": 0.15,
    "waveFeePct": 2,
    "minAnswerTfuel": 0.27,
    "freePerUserPerDay": 5,
    "payout": "0xcb20457aeb7ad30dbae281efbfd7c48137db1894",
    "hours": { "alwaysOpen": true }
  },
  "knowledge": [
    "v3:12",
    { "title": "Overview", "text": "BrainVault is permanent on-chain storage." }
  ],
  "engine": "llm"
}

8. Frequently Asked Questions (FAQ)

Q1: Why does a .theta name need its owner to sign during publishing?

The TNS public resolver (0x428101CB7a0D22587a6f098A518c36Af2a1b2E31) enforces on-chain ownership. Executing setText(node, "wave.bot", "v3:<listing_id>") changes the official domain record for <name>.theta, so the transaction must be signed by the wallet that owns the name. If a different wallet is connected during wizard step 5, the wizard shows an ownership notice with the owner address and allows skipping name resolution while keeping all minted cards intact.

Q2: What does "Minted, not live" mean?

"Minted, not live" indicates that all bot cards (mascot avatar, rules, listing, knowledge) are successfully written to the BrainVault v3 contract on Theta chain 361, but the live endpoint verification (waveApi?action=check) has not yet confirmed the TNS wave.bot pointer or domain propagation. Clicking "Check again" re-polls the live status endpoint.

Q3: What is a dry run in the Publish Bot wizard?

A dry run is triggered via the "Check only" button in the wizard or during AI recipe ingestion. It runs steps 1 through 3 (Review, Preflight Schema Checks, and Cost Calculation) without prompting for wallet signatures or spending TFUEL. It validates all card payload schemas and calculates an exact itemized cost breakdown.

Q4: What does publishing a bot cost?

Publishing a new bot costs about 4 TFUEL: the mascot design card (about 1.7 TFUEL), the rules and listing cards (about 1 TFUEL each), and about 0.25 TFUEL to point the name. New knowledge cards add about 1.7 TFUEL per 2.5 KB. The wizard shows the exact itemized total before you sign. Cards with identical content sha256 hashes are automatically reused, costing 0 TFUEL for duplicate minting.