SuiMesh Docs

01

Protocol Overview

Understand how SuiMesh separates ordinary chat from high-stakes actions that affect money, permissions, contract state, or external systems.

Read flow ->

02

Trusted Actions

Agent summaries are treated as untrusted. The PTB bytes, inspected facts, simulated effects, and policy decision become the security root.

View checks ->

03

Architecture

Connect clients, wallets, dApps, agent frameworks, transport adapters, Walrus storage, Seal access control, and Sui trace guards.

See layers ->

04

Examples

Run local examples, Move checks, live messaging recovery, heavy action execution, Walrus archive restore, and full testnet regression flows.

Start building ->

01

Mission

SuiMesh exists so humans, wallets, dApps, and AI agents can share the same trusted context without locking that context inside one app database or one agent backend.

Agent interconnection

SuiMesh is not a chat app, an agent wallet, or a trading bot. It is the protocol layer that lets apps, clients, wallets, and agent frameworks publish and recover the same communication state.

Client adapters can connect web apps, CLI tools, Telegram or Discord bridges, wallets, and Sui apps.
Agent adapters let existing frameworks publish proposals and reports without becoming a SuiMesh runtime.
Transport adapters deliver signed SuiMesh events while keeping protocol semantics portable.

Behavior audit onchain

When an agent prepares a transaction, contract call, permission change, trade, or other side effect, SuiMesh creates a trace that can be inspected, claimed, executed, completed, failed, restored, and verified.

Policy approves objective PTB facts, not friendly prose.
ActionClaim works as an execution lock to prevent duplicate execution.
ExecutionReceipt and AuditEvent close the record with a verifiable result.

02

Light path and heavy path

SuiMesh keeps normal communication lightweight, then switches to a stricter chain of events whenever an agent action can move value, touch permissions, change contract state, trade, or create an external side effect.

Light Path

Ordinary conversation and context messages stay simple. A user message can lead to an agent message and optional memory receipt without requiring onchain claim coordination.

UserMessage -> AgentMessage -> optional MemoryReceipt

Heavy Path

High-stakes actions become a trace. Every important state transition is encoded, hashed, linked, and recoverable.

Intent -> Proposal -> SuiPtbAction -> Inspect -> Simulate -> PolicyDecision -> ActionAnchor -> ActionClaim -> ExecutionReceipt -> AuditEvent

03

Core capabilities

Portable communication state

Conversations, intents, proposals, actions, decisions, receipts, audit records, and memory receipts become protocol state. A user can recover the same session from another client instead of trusting one product to remember everything.

PTB action verification

v0.1 normalizes heavy actions into sui.ptb.v1. Business meaning sits in the semantic type and template, while the real source of truth remains the PTB bytes and the facts extracted from them.

Transfer, Move call, swap, copy trading, prediction market, or unknown semantic type.
Manifest validation must match inspected PTB facts.
Unknown or opaque PTB bytes cannot silently pass as low risk.

Policy before execution

The policy engine evaluates extracted and simulated facts. Built-in v0.1 guards include value-at-risk limits, recipient allowlists, package and function allowlists, slippage limits, expiration checks, risk-level handling, and unknown-contract handling.

Trace guard and receipts

Trace guards anchor approved actions, authorize an executor, enforce expiry, create a claim lock, and require the claimant to complete or fail the action. The receipt records transaction digest, effects hash, status, and errors.

04

Architecture

The protocol is adapter-first. SuiMesh core defines event semantics, encoding, verification, policy, trace state, receipts, and audit records; integrations decide how events move, where archives live, and how access is granted.

Application / Agent Framework

Web apps, wallets, dApps, CLIs, Telegram or Discord bridges, and agent frameworks become entry points into one shared SuiMesh event stream.

SuiMesh SDK Core

The SDK provides the client facade for light messages, PTB proposals, inspect/simulate, policy evaluation, trace recording, restoration, and verification.

EventTransport Binding

Transport adapters send, list, subscribe, and optionally discover authorized sessions. The current implementation includes a Sui Stack Messaging adapter.

Storage / Memory / Policy / Trace

Pluggable adapters handle encrypted context archives, memory receipts, action registries, PTB inspection, policy engines, local guards, and Sui Move trace guards.

Sui / Walrus / Seal / Executors

Sui coordinates lightweight proof and trace state, Walrus stores encrypted context archives, Seal controls access, and executors or wallets submit approved actions.

Walrus stores context

Encrypted messages, proposal detail, PTB payloads, policy facts, simulation results, receipts, audit detail, and memory receipts.

Sui proves the trace

Trace IDs, proposal refs, action hashes, decision refs, receipt refs, status, claim state, and timestamps.

Seal controls access

Who can read, recover, rotate access, and lose access to archived communication context.

05

End-to-end action flow

0-1

Session and light context

A client, dApp, wallet, or bridge writes user and agent messages into a session. Memory providers can add recall or remember receipts.

2-3

Heavy boundary

When the agent proposes money, permissions, contract state, trading, or another side effect, it must publish a structured proposal and SuiPtbAction.

4-5

Inspect and policy

The inspector parses the PTB, simulation adds chain-state facts, and policy records approved, rejected, or requires-confirmation.

6-7

Anchor, claim, execute

The trace guard anchors approved action state, the authorized executor claims it, and the executor records an execution receipt.

8-9

Audit and restore

The audit event links the trace to archived detail. Another client can restore events, verify hash chains, check digests, and decrypt if allowed.

06

Build with SuiMesh

The current repository is a hackathon-stage protocol SDK with local tests, Move checks, live testnet flows, Walrus archive restore, Sui Stack Messaging transport, and integrated business regression.

Run the SDK locally

Install dependencies, run strict checks, Move tests, dependency audit, and a minimal example.

bun install bun run check:strict bun run test:move bun run audit:deps bun run example:minimal

Minimal client

Use the default client with in-memory adapters to send a light message and receive a verifiable event hash.

import { createSuiMeshClient } from "./src/index.ts"; const client = createSuiMeshClient(); const message = await client.light.sendMessage({ sessionId: "session-1", actor: { role: "user", id: "alice" }, content: "Prepare a 1 MIST transfer proposal." });

Live testnet coverage

The full regression covers typecheck, unit tests, remote messaging, agent proposal verification, onchain heavy action execution, Walrus archive, and business recovery.

test:live:messaging
test:live:agent-proposal
test:live:heavy
test:live:walrus
test:live:full-regression

07

Repository map

Protocol and encoding

packages/protocol defines event, action, policy, receipt, and trace types.
packages/codec handles JSON envelopes, BCS codec, and blake2b-256 hashing.
packages/sdk exposes the SuiMeshClient facade.

Action safety

packages/ptb-inspector extracts Sui PTB facts and fixtures.
packages/policy-engine evaluates built-in v0.1 guards.
packages/trace-guard provides local and onchain trace coordination.

Integrations

packages/storage includes Walrus and local encrypted context storage adapters.
packages/transport defines delivery and session discovery interfaces.
packages/sui-stack-adapter binds Sui Stack Messaging to SuiMesh events.

08

When to use SuiMesh

Auditable agent actions

You need proof of what the user requested, what the agent proposed, what policy approved, who claimed execution, and what result was recorded.

Cross-client recovery

You want users to recover the same conversation, memory, task history, and audit trail from another wallet, app, bot, or client.

Sui-native execution

Your workflow depends on transfers, Move calls, Sui PTBs, object state, package selectors, testnet execution, or Sui Move trace guards.

Agent ecosystems

You are building agent-to-agent, agent-to-wallet, or agent-to-dApp coordination where a prose summary is not enough for trust.