Soliton

Onchain autonomous intelligence with verifiable memory.

Soliton is an onchain autonomous intelligence workspace. It gives long-running agents a durable, inspectable work loop: execute through Hermes, persist generated memory through Walrus/MemWal, reference Sui wallet/payment/account/delegate state, and expose the resulting proof fields in the dashboard.

The product claim is narrow and testable: agents become more useful when their memory is durable, portable, inspectable, and verifiable through Walrus, MemWal, and Sui.

Soliton is not a generic LLM wrapper with a blockchain label. Sui and Walrus improve the agent system itself.

Public Source Boundary

This Bloch-Lab public repository intentionally excludes the production frontend source, distinctive visual design, and brand animation assets. The public tree keeps the backend/runtime code that matters for review: Sui billing, wallet verification, Walrus/MemWal memory adapters, Hermes runner integration, Supabase migrations, operations scripts, and documentation. The deployed private website is maintained separately.

Onchain Proof Loop

Soliton has four lanes:

• Hermes execution and work loop: queued agent_tasks become Hermes Kanban work, and the runner writes task provenance back into MemWal-backed logs.
• Walrus/MemWal durable memory and recall: generated notes, graph snapshots, runner logs, summaries, and artifacts are stored through the memory adapter and recalled by later work.
• Sui wallet/payment/account/delegate references: Slush/Sui wallet signatures, native SUI payment digests, MemWal account IDs, and delegate metadata provide account and access context.
• Dashboard proof inspection: users can inspect providers, namespaces, hashes, Blob IDs, Sui object/event fields, MemWal account IDs, delegate status, read results, and verify results.

Soliton treats Supabase as an index/cache. The trust claim must come from visible memory records, Sui references, and read/verify results, not from database rows alone.

Every serious Sui/Walrus claim in the UI should resolve to one or more of:

• provider: memwal, walrus_http, or clearly labeled local
• namespace
• content hash
• Walrus Blob ID
• Sui object ID
• Sui event digest
• MemWal account object ID
• delegate status
• read/verify result

Local fallback is allowed for development and demos without credentials. It must stay labeled as fallback and must never be presented as live Walrus proof.

Hermes provides inspectable task provenance, not cryptographic execution verification. Soliton includes a tiny Seal-ready private capsule demo that encrypts an artifact envelope, stores it through the memory adapter, prefers direct Walrus HTTP when configured, and exposes a seal_policy_id. This is not real Mysten Seal policy encryption yet. Soliton does not claim ZK proofs, private transactions, private Walrus storage, or Seal-encrypted memory unless a future implementation adds and exposes those records.

First Demo Path

Use this path when explaining or judging the project:

1. Inspect the public memory surface at /try. No wallet or setup is required.
2. Connect a Soliton memory identity at /wallet with Google auth plus a Slush/Sui wallet signature.
3. Pay for AI credits at /dashboard/payment, then inspect the Sui digest, treasury address, checkpoint, MIST received, and credit ledger row.
4. Create a graph-backed Hermes task from /dashboard/agents. Soliton seeds a memory project, syncs graph nodes/edges, and stores wiki_page plus graph_snapshot records.
5. Run the agent runner so Hermes receives a task prompt with recovered Walrus Memory context and writes a runner log after handoff.
6. Prove the memory on /dashboard/memory by inspecting provider, namespace, hash, Blob ID, Sui object/event, MemWal account, delegate, and Seal policy fields when those fields exist.
7. Recall prior records from /dashboard/agents by project namespace in a later task or recall query.
8. Verify and read stored provider content from /dashboard/agents, using raw read mode only when you need the immutable stored blob.

If the demo only shows a chatbot, it is the wrong demo. The important moment is durable memory being stored, recalled, inspected, and verified.

What Exists Now

• Walrus/MemWal memory schema in supabase/migrations/0020_sui_walrus_memory.sql
• Provider-neutral memory adapter in engine/memory/*
• MemWal, direct Walrus HTTP, and local fallback providers
• Memory APIs in src/app/api/memory/*
• Project/wiki storage hooks that write generated bundles, pages, and graph snapshots through the adapter
• OpenClaw-free graph note ingestion through POST /api/memory/graph-note
• /dashboard/graph can display Hermes/Walrus graph projects without an OpenClaw workspace slug
• Dedicated /dashboard/payment for Slush/Sui credit top-ups and reconciled payment history
• Dedicated /dashboard/memory for provider-aware proof cards that hide empty Blob/Sui/Seal fields
• Hermes runner recall before handoff and runner log storage after handoff through engine/memory/runner.mjs
• Minimal public shell pages for route discoverability; production frontend source is private
• npm run memory:preflight
• npm run memory:demo
• Seal-ready capsule route and CLI demo through POST /api/memory/seal-capsule and npm run memory:seal-demo
• Public runtime source without proprietary frontend design assets
• Minimal Sui Testnet receipt package in move/soliton_receipt, published at 0x2a3a7067ebed7452f2a1ea438a6abfac4f0a81757682617f90ae94488e38c0d6
• Slush/Sui billing for AI credit top-ups, verified by Sui transaction digest and treasury balance change
• Vercel-ready Next.js runtime posture with Node 22.x and Hobby-compatible long route durations

Wallet identity and AI credit billing now use Slush/Sui. Sui, Walrus, and MemWal are the memory proof layer.

The Sui Testnet package is intentionally narrow: memory_receipt::create_receipt anchors a namespace, content hash, provider, optional Walrus Blob ID, optional Sui reference, and metadata URI into a MemoryReceipt object plus event. A sample receipt object was created at 0xd6dc1eaf351be76accb1b9215e18d21d902019aceacef783157dc2f641f3dc0c for the graph proof Blob YsPV1ASNC7FiHt-fxRu4zNIPLQsJkko7sRn9Q9tvKGM.

Architecture

flowchart TD
  User["User"] --> UI["Next.js app<br/>/try /wallet /dashboard/*"]
  UI --> Supabase["Supabase<br/>Auth, Postgres, RLS"]

  UI --> WalletPage["Wallet surface<br/>/wallet"]
  WalletPage --> WalletAPI["Wallet APIs<br/>challenge, verify, workspace-task"]
  WalletAPI --> SuiRPC["Sui RPC"]
  WalletAPI --> WalletRows["Wallet identity index<br/>sui_wallet_identities"]
  WalletRows --> Supabase

  UI --> PaymentPage["Payment surface<br/>/dashboard/payment"]
  PaymentPage --> Billing["Sui billing APIs<br/>estimate, quote, confirm"]
  Billing --> SuiRPC
  Billing --> Treasury["Sui treasury<br/>native SUI transfer"]
  Billing --> PaymentRows["Payment index<br/>quotes, payments, credit ledger"]
  PaymentRows --> Supabase

  UI --> GraphNote["Graph note API<br/>POST /api/memory/graph-note"]
  GraphNote --> GraphCache["Graph cache<br/>wiki pages, nodes, edges"]
  GraphNote --> Memory["Memory adapter<br/>engine/memory"]

  UI --> AgentAPI["Agent task API<br/>POST /api/agents/tasks"]
  AgentAPI --> Tasks["Task queue<br/>agent_tasks"]
  Tasks --> Runner["Agent runner"]
  Runner --> Memory
  Runner --> Hermes["Hermes<br/>agent profile"]

  UI --> MemoryUI["Proof surfaces<br/>/dashboard/memory + /dashboard/agents"]
  MemoryUI --> MemoryAPI["Memory APIs<br/>records, recall, read, verify"]
  MemoryUI --> SealCapsule["Seal-ready capsule API<br/>POST /api/memory/seal-capsule"]
  MemoryAPI --> Memory
  SealCapsule --> Memory

  Memory --> MemWal["MemWal<br/>semantic memory"]
  Memory --> Walrus["Walrus HTTP<br/>blob storage"]
  Memory --> Local["Local fallback<br/>clearly labeled"]
  Memory --> Proof["Provider-aware proof fields<br/>hash, namespace, Blob,<br/>Sui object/event, MemWal account,<br/>Seal policy when present"]
  Memory --> Supabase

Loading

Layer	Role
src/app	Next.js routes, pages, API handlers
src/app public shell	Minimal route placeholders plus API handlers; production frontend source is private
engine/agents	Agent provider registry, tasks, runner
engine/memory	MemWal, Walrus HTTP, and local fallback adapter
supabase/migrations	Database schema and RLS
docs	Architecture, operations, and implementation notes
ops/scripts	Maintenance and demo scripts

Key boundaries:

• Agent work does not run inside a web request.
• Provider calls should stay isolated under engine/memory/*.
• Supabase indexes memory records, but it is not the source of the Walrus/Sui proof.
• Private keys and service-role credentials must never reach client components.
• The Agentic Web track is not satisfied until Soliton has a real Sui transaction flow with preview, guardian checks, explicit confirmation, and testnet execution.

Quick Start

npm install
cp .env.example .env.local
npm run dev

For Slush/Sui wallet testing, prefer HTTPS:

npm run dev:https

Open:

http://localhost:3000

When using dev:https, open:

https://localhost:3000

Useful first routes in the deployed private app. In this public repository, these render minimal placeholders while the APIs remain reviewable:

• /try - public memory preview
• /wallet - wallet identity and workspace request
• /dashboard - workspace overview
• /dashboard/payment - Sui credit top-up and payment receipts
• /dashboard/agents - task queue, recall/read/verify controls, and Seal-ready capsule creation
• /dashboard/memory - provider-aware memory proof console
• /dashboard/graph - indexed graph nodes and edges for memory projects
• /dashboard/wiki - generated memory workspace and legacy artifact view

Required Checks

npm run typecheck
npm run build
npm run memory:preflight
npm run memory:demo
npm run agent:preflight
npm run billing:sui:preflight
npm run memory:seal-demo

npm run memory:preflight validates the memory path. It will fail or warn in environments missing Supabase service credentials, MemWal credentials, or Walrus endpoints. That is expected until live provider config exists.

For MemWal, memory:preflight checks SDK import, relayer health, and a small write probe. A 401 means the account ID, delegate key, or relayer environment does not match.

npm run memory:demo writes through the same provider order as the runner: MemWal, then direct Walrus HTTP, then local. By default it fails if the result is local and only indexes a proof row after a live provider succeeds. Use npm run memory:demo -- --allow-local only for offline development.

Run npm run billing:sui:reconcile -- --lookback-hours=72 after live testnet top-ups. It checks Sui payment rows, credit ledger rows, quote metadata, and treasury movement against recent confirmed digests.

Vercel Deployment

The web app deploys as a standard Next.js app. package.json pins the Vercel runtime to Node 22.x, and long API routes are capped at maxDuration = 300 for Hobby-plan compatibility.

Vercel runs the UI and API routes. Hermes execution still needs a separate worker process or host with HERMES_BIN, SUPABASE_SERVICE_ROLE_KEY, and the same memory/Sui environment configured:

npm run agent:preflight
npm run agent:runner -- --limit=1

For Google auth, set the deployed app URL as the Supabase site URL and include https://your-domain.example/auth/callback in Supabase and Google OAuth redirect settings.

Environment

Base app:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_your_key
# or NEXT_PUBLIC_SUPABASE_ANON_KEY=your_legacy_anon_key
NEXT_PUBLIC_SITE_URL=http://localhost:3000
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Sui/Walrus memory:

SUI_WALRUS_MEMORY_ENABLED=true
SUI_WALLET_IDENTITY_ENABLED=true
SUI_NETWORK=testnet
SUI_RPC_URL=https://fullnode.testnet.sui.io:443

MEMWAL_ACCOUNT_ID=0x...
MEMWAL_DELEGATE_PRIVATE_KEY=...
MEMWAL_RELAYER_URL=https://relayer-staging.memory.walrus.xyz
MEMWAL_NAMESPACE_PREFIX=soliton

# Optional for CLI demos. If omitted, memory:demo reuses the first Supabase
# auth user. If no user exists, run once with:
# npm run memory:demo -- --create-demo-user
MEMORY_DEMO_USER_ID=

WALRUS_PUBLISHER_URL=
WALRUS_AGGREGATOR_URL=
WALRUS_DEFAULT_EPOCHS=2

# Optional server secret for the Seal-ready capsule demo.
# Use a long random value; this is not a Mysten Seal key.
SEAL_DEMO_SECRET=

Sui billing through Slush:

SUI_TREASURY_ADDRESS=0x...
SUI_PAYMENT_NETWORK=testnet
SUI_RPC_URL=https://fullnode.testnet.sui.io:443
SUI_QUOTE_TTL_MS=300000

# Optional testnet/devnet/localnet override for affordable demos.
# Ignored on mainnet. 1000000000 MIST = 1 SUI.
SUI_TEST_PAYMENT_MIST=1000000000

Hermes runner:

HERMES_AGENT_ENABLED=true
HERMES_BIN=hermes
HERMES_DEFAULT_PROFILE=app-dev

Never expose these to the browser:

• SUPABASE_SERVICE_ROLE_KEY
• MEMWAL_DELEGATE_PRIVATE_KEY
• private wallet keys
• privileged RPC secrets
• AWS keys
• OpenAI keys
• Telegram tokens
• SSH secrets

Database

Run Supabase migrations in order.

Important migrations:

• 0019_agent_orchestration.sql - agent tasks, events, wallet identities, challenges, indexes, triggers, and RLS
• 0020_sui_walrus_memory.sql - Sui wallet identity, MemWal accounts, delegate keys, and walrus_memory_records
• 0021_sui_credit_purchases.sql - Sui payment quotes, Slush/Sui receipts, credit ledger link, and purchase application
• 0022_sui_wallet_identity_challenges.sql - extends wallet challenges so Slush/Sui identity signatures can be verified and indexed
• 0015_solana_credit_purchases.sql - legacy SOL payment quotes, payments, credit ledger, and purchase application

Do not rename historical tables casually. Migration history is part of the product state.

Memory API

Important routes:

• GET /api/memory/records
• POST /api/memory/recall
• GET /api/memory/read
• POST /api/memory/verify
• GET /api/memory/preflight
• POST /api/memory/graph-note
• POST /api/memory/seal-capsule

Memory records are indexed in walrus_memory_records with provider metadata, hashes, namespaces, artifact relations, and proof fields.

GET /api/memory/read returns Seal-ready capsule content as cleaned, pretty JSON by default so the demo receipt stays product-facing. Use ?raw=1 when you need the immutable provider bytes that /api/memory/verify hashes.

Provider meanings:

• memwal - live semantic memory through MemWal
• walrus_http - live blob storage through Walrus publisher/aggregator endpoints
• local - development fallback, never live Walrus proof

Agent Runtime

Soliton queues work; a separate runner executes it.

Flow:

1. UI can create a graph-backed memory note through POST /api/memory/graph-note.
2. UI creates an agent_tasks row tied to the memory project.
3. Runner claims queued work.
4. Runner recalls project memory through engine/memory/runner.mjs, merging MemWal recall with indexed memory records.
5. Runner delegates to Hermes when enabled.
6. Runner stores logs and summaries through engine/memory/runner.mjs.

Current state: live MemWal write probe and Hermes preflight pass in the configured workspace. The main demo path no longer requires OpenClaw for graph display: /dashboard/agents seeds a project graph, stores wiki_page and graph_snapshot memory records, and queues Hermes work against that project namespace.

Validation:

npm run typecheck
npm run build
npm run memory:preflight
npm run agent:preflight
npm run agent:runner -- --dry-run --limit=10

In this local workspace, typecheck and build pass. For a live runner memory proof, queue one graph-backed task from /dashboard/agents, run one non-dry-run queued task with Supabase service credentials, Hermes enabled, and either MemWal credentials that pass memory:preflight or Walrus HTTP endpoints configured. Confirm the graph records and resulting agent_task_events metadata point to walrus_memory_records rows whose provider is memwal or walrus_http.

Useful commands:

npm run agent:preflight
npm run agent:runner -- --dry-run --limit=10
npm run agent:runner -- --limit=1

Hermes is the primary orchestration layer. OpenClaw through clawmacdo is optional advanced runtime infrastructure, not required for the base memory proof.

Live Provider Checklist

Before claiming live Walrus/MemWal proof:

1. Run migrations through 0022 for wallet identity, Sui billing, memory proof, and dashboard inspection.
2. Configure Supabase service role on the server.
3. Configure MEMWAL_ACCOUNT_ID and MEMWAL_DELEGATE_PRIVATE_KEY, or configure current Walrus publisher/aggregator endpoints.
4. Configure SUI_TREASURY_ADDRESS, SUI_PAYMENT_NETWORK, and Sui RPC for /dashboard/payment.
5. Ensure at least one Supabase auth user exists, or set MEMORY_DEMO_USER_ID for CLI demos.
6. Run npm run memory:preflight, npm run agent:preflight, and npm run billing:sui:preflight.
7. Queue a graph-backed task in /dashboard/agents, or run npm run memory:demo.
8. Open /dashboard/graph and confirm the indexed nodes/edges are visible for the project.
9. Confirm walrus_memory_records.provider is memwal or walrus_http.
10. Open /dashboard/memory and inspect provider-specific fields. Empty Blob/Sui/Seal fields should be hidden, not displayed as missing proof.
11. Recall, read, and verify at least one record from /dashboard/agents.
12. Optionally create one Seal-ready private capsule in /dashboard/agents, or run npm run memory:seal-demo, and show its seal_policy_id.
13. If the provider is local, call it fallback.

Current Next Work

The highest-value next steps are:

1. Replace the Seal-ready demo envelope with real Seal policy encryption and allowed/denied read behavior.
2. Add live MemWal account/delegate status refresh, including revoked, stale, missing, and configured states.
3. Write the final Sui Overflow operator runbook with env vars, migrations, commands, proof fields, and fallback behavior.
4. Record the authenticated browser demo for wallet/payment, graph memory, Walrus/MemWal storage, Hermes recall, and dashboard proof inspection.
5. Optionally publish a public proof appendix through Walrus Sites after the core memory loop remains stable.

Commands

npm run dev
npm run typecheck
npm run build
npm run check
npm run start
npm run agent:preflight
npm run agent:runner -- --dry-run --limit=10
npm run billing:sui:preflight
npm run billing:sui:reconcile -- --lookback-hours=72
npm run memory:preflight
npm run memory:demo
npm run memory:seal-demo
npm run wiki:backfill -- --email owner@example.com --dry-run
npm run admin:load -- --email owner@example.com --replace

npm run check runs typecheck and build. There is no lint or unit-test script yet.

Product Truths

• Soliton is onchain autonomous intelligence with verifiable memory, prepared primarily for the Walrus track.
• Sui/Walrus must make the agents better, not decorate the UI.
• Local fallback is honest fallback.
• Supabase is the index/cache.
• Slush/Sui is the live wallet identity and billing path.
• The dashboard must show proof fields.
• One working end-to-end proof beats broad unfinished blockchain surface area.