say-ur-intent

# Say Ur Intent

Say Ur Intent is a local-first Sui review and evidence layer for AI clients.

It turns a supported AI-requested Sui action into a local review page where the
user reads the transaction summary, inspects the transaction (PTB) as a graph,
and signs in their own wallet. The AI client never receives signing authority or
executable transaction bytes.

![Say Ur Intent local review page](https://raw.githubusercontent.com/stelis-dev/say-ur-intent/main/assets/review-page.png)

*The local review page: deterministic review checks, review-time simulation
evidence, and the transaction shown as a labeled PTB graph — what the user
reviews before signing in their own wallet.*

For natural-language Sui DeFi questions, the current release also returns
verified, AI-readable evidence before any transaction is built. That answer path
stays separate from account-bound swap review, where the review server builds
local unsigned transaction material internally and, once every review evidence
stage completes, the local review page offers a digest-gated byte handoff,
user-controlled wallet signing, and execution-receipt recording. MCP responses
never sign, execute, or return transaction bytes; the only transaction-byte path
is the same-machine, digest-gated wallet handoff initiated from the local review
page.

That guarantee is byte-level: the bytes you approve are the bytes your wallet
signs — not a claim that the human-readable review captures every detail of the
transaction, so the raw PTB structure and addresses stay inspectable beside it.

Users can ask ordinary questions:

- "Can I cover a 1000 dollar payment with my assets?"
- "How much are my USD-denominated assets together?"
- "What is the shortfall?"

The broader product direction does not stop at pre-execution review. From
verified evidence, Say Ur Intent aims to carry an AI client's or MCP server's Sui
payment or action request through a human-readable local review and on to
user-controlled wallet signing and execution receipt evidence — only after Say Ur
Intent independently builds or verifies the transaction material. The three
layers below state what is implemented today, what is deliberately sequenced
next, and what stays permanently out of scope. For any
such request, Say Ur Intent explains what current verified evidence supports, what
choices remain with the user, and what claims are unsupported.

## Product Direction in Three Layers

Say Ur Intent is one product, but it must be read at three distinct layers. Do not collapse them:

- **Implemented today:** Sui mainnet evidence, local review, and signable review adapters for the DeepBook and FlowX swap routes. The account-bound DeepBook swap review builds unsigned transaction material into a local in-process material store, internally binds a Sui transaction digest to that stored material, derives object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts, emits a schema-validated wallet review contract with a PTB visualization on a `ready_for_wallet_review` state, and serves a digest-gated byte handoff to the same-machine review page for user-controlled wallet signing with execution receipts recorded on the session. MCP responses do not contain transaction bytes, signing data, or signing readiness.
- **Deliberately sequenced next (planned order, ships only after verified review):** server-side receipt verification against chain state, further protocol adapters beyond DeepBook and FlowX registered through the descriptor contract (protocol names appear only after a concrete support decision), and richer local analysis views. Each step ships only from independently built or verified transaction material with a human-readable local review.
- **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.

In one sentence: Say Ur Intent is a local-first Sui intent evidence and review layer that progresses from verified evidence to user-controlled wallet signing only after Say Ur Intent independently builds or verifies the transaction material and shows a human-readable local review.

DeepBook and FlowX are the current Sui liquidity and price sources in this
release: DeepBook provides scoped conversion, price, and orderbook evidence, and
FlowX provides indicative CLMM route quotes. Wallet and Sui balance reads
describe held assets. They do not define the whole product.

Say Ur Intent does not custody funds, hold private keys, or autonomously trade
on behalf of users.
By current design, it does not rank venues, choose routes, make best-price
recommendations, or silently choose settlement tokens for users.

The current release can build local unsigned transaction material inside the
account-bound DeepBook and FlowX swap review paths. It does not expose
transaction bytes.
Wallet signing is user-controlled on the local review page after a
digest-gated handoff; MCP responses never request signatures, provide signing
readiness, or execute payments.

Current review sessions are local evidence-review records only. DeepBook review
state may show that local transaction material was built, internally bound to a
Sui transaction digest, and used to derive object ownership, quote/policy
provenance, human-readable review facts, and review-time simulation evidence.
Review sessions do not contain
public transaction bytes, signing requests, or executable wallet actions.

The current release flow is:

```text
The user states an intent in natural language.
Say Ur Intent resolves the supported Sui mainnet evidence surface.
The AI answers only from returned evidence and boundaries.
Supported swap transaction material build is an account-bound review step, not
part of the natural-language intent evidence answer.
```

The current release implements intent evidence for supported Sui mainnet reads.
It can also create a read-only, non-signable local review session from a
structured external payment or Sui action proposal. External proposal ingestion
does not trust external transaction material or send anything for wallet signing.

For setup, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
For the MCP API reference, see [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
For the AI-client answer playbook, see [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md).
For manual maintainer and developer utilities, see [docs/UTILITY_INDEX.md](docs/UTILITY_INDEX.md).

User-question flows for USD-denominated coverage, balance totals, and shortfall answers live in [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md). The response fields for those answers live in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).

## What Works Today

The current release can run as a local stdio MCP server and expose mainnet Sui DeFi evidence:

- wallet balances with verified display units;
- coin-balance classification;
- USD-denominated settlement asset groups derived from pinned DeepBook SDK registry metadata;
- intent evidence with response summaries for natural-language USD-denominated payment coverage, balance-total, and shortfall questions;
- DeepBook pools, tokens, mid price, orderbook context, raw quotes, display-amount quotes, and account inventory;
- FlowX CLMM pools and indicative single-hop swap route quotes from the chain-verified pinned registry;
- user-requested bounded Sui transaction digest lookup, account activity scans, sent-function activity scans with known-wallet-only persistence, and stored normalized activity summaries;
- read-only external proposal review sessions that display proposed action, asset flow, recipient or target, freshness, missing evidence, user choices, unsupported claims, and non-signable reason;
- local Say Ur Intent review evidence and review-session status reads;
- account-bound DeepBook and FlowX swap review progress through local unsigned transaction material build, internal Sui transaction digest binding, object ownership evidence, quote/policy provenance binding, human-readable review facts, and review-time simulation evidence; when every stage completes the review reaches `ready_for_wallet_review` and the local review page offers a digest-gated byte handoff, user-controlled wallet signing, and execution-receipt recording. MCP responses never sign, execute, or return transaction bytes; transaction bytes flow only through the same-machine, digest-gated wallet handoff initiated from the local review page.

It also includes:

- a local review server bound to `127.0.0.1`;
- a local SQLite store for active account read context and review evidence;
- MCP output checks that reject forbidden executable, signing, token, seed, and
  key-material field names from responses.

## Current Limits

### Not Implemented

Server-side receipt verification against chain state is not implemented. The
full analysis page is not implemented. External proposal execution is not
implemented. Transaction material build, contract emit, digest-gated wallet
handoff, and user-controlled signing are implemented for the account-bound
DeepBook and FlowX swap review through a plan-factory registry.

External proposal ingestion is implemented only for read-only local review
sessions. It accepts structured proposal facts, rejects forbidden executable or
signing fields, recognized Sui private-key strings, valid English BIP39
mnemonic phrases, obvious sensitive markers, and suspicious raw secret-like
payloads before storage, and records why the review is non-signable.

Blocked signing is session-scoped: a review session stays blocked while
required review evidence is missing for that session (for example
`wallet_review_contract_emit_missing`). When an account-bound supported swap
review completes local transaction material, digest binding, object ownership,
quote/policy provenance, human-readable review evi