# mintrr

> mintrr supplies blockchain expertise and chain-facing asset/workflow tools for
> a business the operator and harness already understand. Use actual implemented
> callers and evidence; the business/game engine remains with the harness.

The bundled skills provide domain guidance, not execution permission. The approved
modular policy/profile architecture is a development target, not a set of new
available tools. Preferences do not grant roles, signing authority or approval.
AI can use supported CLI or MCP paths, but a transport switch is not authority.
This does not activate hosted payment rails or a managed signer.

## Agent/tool safety boundary

- **It cannot sign.** No tool signs a transaction. The maximum output is an
  unsigned transaction plus signing instructions.
- **It cannot return a secret.** No tool returns a private key, mnemonic or
  provider credential.
- **It cannot broadcast without a human.** Mainnet broadcast requires a
  per-chain confirmation phrase that the operator types.
- **The gas payer never becomes the owner.** Owner and payer are asserted
  distinct; a constructor mint to the payer is rewritten to the owner.

Do not assume an unlisted tool exists. An extension may be possible, but is not
an implemented or authorized operation merely because a guide proposes it.

## MCP tools (24)

Read and truth:
- `mintrr_health` - service status and chain maturity
- `mintrr_templates` - first-party templates with their feature matrix
- `mintrr_skills` / `mintrr_get_skill(skill_name)` - list bundled modules and fetch a full guide

There is deliberately no tool that returns contract source. A generated contract
is an output you receive when you deploy; the templates behind it are the
operator's, and they are not readable through this interface at any scope.

Analyse and review:
- `mintrr_analyze(source, abi_json)` - read-only contract analysis
- `mintrr_analyze_market(address, chain, network)` - read-only analysis of a
  deployed prediction-market contract, including its settlement wiring
- `mintrr_review(plan)` - review a token plan against the guardrails

Plan and prepare:
- `mintrr_plan_catalog()` - authenticated-read schema/template/feature labels for drafts; labels are not authority
- `mintrr_plan_preview(plan, template)` - schema validation and candidate template selection; no generation, compile, save, signing, RPC or model call
- `mintrr_plan_compose(goal, owner_address, constraints)` - draft a plan from
  intent for a named deploy owner
- `mintrr_plan_refine(session_id, feedback)` - refine a plan
- `mintrr_dry_run(plan, template)` - gas, roles and address preview; no writes
- `mintrr_bundle_preview(chain, issuer, name, symbol, cap, seizer, underlying, blocked_countries, max_wallet_holdings, max_transfer_amount, cooling_period_seconds)` - compile and order the RWA bundle (identity registry, compliance module, security token) and report each compliance rule's configured or unset state and units; no signing, no broadcast. Rule values are optional and identical on CLI, API and MCP: `blocked_countries` are ISO-3166-1 numeric codes (1..999); `max_wallet_holdings` and `max_transfer_amount` are HUMAN units scaled exactly once to token base units and asserted at that figure; `cooling_period_seconds` 0 disables. Omitted rules stay unset and are asserted on chain at their documented unset value (0 = unlimited or off, not a stop). The token deploys with totalSupply 0 (no premint); the issuer mints after deploy.
- `mintrr_session_create(plan, template)` / `mintrr_session_step(session_id, action)`
  - the deploy session state machine (dry-run, unsigned export, broadcast)
- `mintrr_multichain_deploy(plan, chains)` - multi-chain preparation
- `mintrr_credits_statements(since, until, outcome, endpoint, idempotency_key, job_id, hold_id, limit, cursor)` - settled credit attempts for your token, newest first
- `mintrr_credits_holds(limit)` - open credit reservations (reserved, not spent)
- `mintrr_credits_grant(token_hash, compute_amount, gas_amount_native, is_unlimited, config)` - admin-only grant/top-up (a local admin credential, or the caller's own admin bearer hosted); `is_unlimited` is a three-state flag (omitted preserves, true enables and sets the balance to the supplied amount, false demotes)

Guide and truth (agents, the guardrail layer):
- `mintrr_suggest_pattern(intent)` - rank architecture patterns for an intent
- `mintrr_patterns()` - the pattern catalogue
- `mintrr_capabilities()` - what mintrr can do, with maturity
- `mintrr_guardrails()` - the refusals and safety rules
- `mintrr_explain_limits(chain)` - per-chain limits and maturity

## Skills (12)

Fetched via `GET /v1/skills` (names are public; content is admin-only).
Bundled skills: `product-rules`, `marker-grammar`, `rituals`, `trust-model`,
`versioning`, `writing-style`, `smart-contract`, `blockchain-ops`,
`compliance`, `security`, `token-economics`, `create-boundary`.

## The maturity ladder

Only `supported` may appear in a capability claim.

- **supported** - live on a real chain with a post-deploy role assertion.
- **code-complete** - built, unit tested and registered, but not proven live.
- **preview** - a claim in waiting.
- **dev** - localhost and Hardhat; never a trust claim.

Arc mainnet is live and its canonical maturity is `supported`.
Arc's bounded mainnet deploy/upgrade/token-transfer and USDC-return trial completed
on 2026-10-18. That sequence does not establish every business workflow or feature.
Hosted eligibility and general managed-signing authority remain unchanged.
The product chain set is locked to Ethereum, Polygon and Arc; no other chain is
offered or pending promotion.

## Chains

<!-- CAPABILITY-FACTS:START -->
Runs on EVM. Supported: Ethereum, Polygon, Arc · USDC gas. Code-complete: none. Compatibility is family level, proof is per chain. Chain facts live in exactly one place; every other chain list in the product derives from it, so they cannot drift apart.
<!-- CAPABILITY-FACTS:END -->

- **Arc** is Circle's L1. Its native gas token is USDC with **18** decimals,
  while the USDC ERC-20 is 6. Do not infer decimals from the symbol.

## RPCs

Ethereum and Polygon mainnets carry a failover list (3 to 4 backup endpoints
each), so a single dead default does not take down reads. Arc mainnet uses its
own official endpoint with no fallback. A custom RPC override suppresses
fallbacks, and mainnet broadcast refuses a public default and requires
`MINTRR_<CHAIN>_RPC`.
The official public Arc endpoint was permitted for that completed local trial
only. It does not change the product-wide mainnet gate or enable MCP signing.

## Verification

Generation refuses a requested feature whose source-marker group is absent.
This is substring evidence, not proof of runtime behavior. Compilation is a
separate check. The optional ABI helper checks function names for only a subset
of features and is not wired into the production compilation path; it does not
check argument compatibility. Do not infer complete interface or behavioral
verification from a successful build.

Per-holder freezing is native and agent-gated on the security-token template.
On compatible plain tokens it can be injected with a weaker owner-gated role.
An artifact missing freeze markers is refused, not evidence that no producer exists.

## Local fleet inventory

`mintrr manage list --json` returns the local fleet projection with optional
`--owner` and `--chain` filters, without AI or RPC. Default output stays human
readable. A row's `features` are saved-plan declarations; `abi_features` are
ABI function-name hints from the stored ABI, and `chain_maturity` is a
canonical registry label. The hints name declared functions only: not
signatures, not authorization, not runtime behavior. The verified flag is
stored metadata, not a fresh chain check, and JSON is not offered for every
management action.

`mintrr manage browse` is an optional read-only terminal navigator over the
same projection (it needs Bun). It browses, selects and shows saved evidence
and guidance only; it never signs or broadcasts and has no payment or wallet
step. Pipes, plain terminals and a `--plain` flag get text mode instead of the
interactive screen. The normal CLI, API and MCP authority is unchanged: no new
MCP tool or endpoint covers it, and it is a bounded fleet navigator, not a
complete business manager.
Deployment transaction hashes can be redacted by the conservative shared sink;
this output is not a complete transaction-receipt export.

`mintrr tui` starts that same read port in a modular workbench shell (also
needing Bun; the `manage browse` behaviour stays unchanged). Slash commands
open first-party entry screens: fleet, manage, create, context, history,
assistant, help. `/context owner|chain|clear` changes the read filters only
and is not an authority or identity change; search mode is a local filter
over the fleet already loaded, and `/refresh` re-reads the local registry.
The assistant is not connected and sends no model or provider request. Create
edits basic draft fields, asks Python for a no-write preview, then requires
explicit review and Export before a local plan file is created. Export is
confined to .local/workbench/plans, refuses existing files and symlinked store
components, and binds the reviewed plan/template/context fingerprint. No source
generation, compilation, signing, transaction, RPC or payment action is connected.
An interrupted/unconfirmed export is uncertain: inspect the store rather than
assuming no file was written. Saved plans are not deployed fleet records.
Terminal shortcuts share one pinned keymap focus-layer model; Ctrl chords can
use terminal-supplied base-layout codes on non-Latin layouts, with direct-layout
matches first. Native input editing and the unsigned/read-only boundary remain.
A shared typed viewport table owns the supported/tested 40x12 floor and 80/120
column layout tiers; below-floor viewports are not newly refused. Existing
visible fleet/catalog reads and draft schema preview have bounded status-only
activity, not percentages or compile/chain proof. Hiding stops animation, not
necessarily the read; existing error/cancellation/export uncertainty remains.
No new compile, bundle, signing, payment or model action is connected. Current
schema-valid draft review can show a local QR for the normalized public owner,
with matching text and small-pane fallback, not a signing URI or ownership proof.
The separate CLI compile/deploy --plan input refusals and saved-plan handoff
are documented in docs/cli.md under compile; error output is text even with --json.
Saved terminal receipts can name a manual local compile command, never execute
it. The shared compiler refuses another source's artifact when its bound artifact
is missing; this is selection evidence, not runtime or provenance proof.
Shared design/compile holds its bounded compile lock before generation and
companion staging. Allowlist genesis binds its allowlisted recipient to the plan's
premint recipient (default owner); a missing or ambiguous initializer refuses
instead of guessing. The shared mint hook checks the scaled supply cap for
constructor genesis and later mint paths. These are preparation guards, not
signing or chain proof.
Local wallet creation/import password confirmation refuses unprotected terminal
fallback and ended input before account creation; see docs/cli.md under wallet.
Manage can show the current session's last export receipt when no deployed
records are loaded; it is not a persistent draft browser or live file check.
Activity is an in-memory list of fixed messages, not a durable audit log, and
credential-shaped input is refused and cleared without storage. No key,
execute, provider or model flag exists in the workbench. CLI draft catalog/preview
and authenticated GET /v1/plans/catalog and POST /v1/plans/preview share the Python
validation decision; API/MCP accept no export path and write no server-side draft.
Catalog maps use plan_schema_json/features_json; preview uses plan_json (JSON
strings to decode as data, not code). Public field names survive the unchanged
redaction sink; credential values remain redacted. schema_valid is not generated
interface, authorization, compliance or live proof. The fingerprint is a drift
guard, not approval or a signature. An interactive terminal that asks for no colour
keeps default colours with keyboard interaction; pipes and non-interactive
runs get the plain text path.
The workbench's keyboard and mouse controls are documented in terminal/README.md
and docs/cli.md and checked against one shared controls table; on-screen Help
uses that same table. Mouse support depends on the terminal, ordinary input
editing stays native, and letter shortcuts do not trigger while typing.
Plain output states why interactive controls are inactive. The public website's
theme is not changed by the terminal's colour and focus treatment.

## Key endpoints

- `GET /v1/health` - chain maturity, deploy status
- `GET /v1/templates` - templates (auth required)
- `GET /v1/skills` - skills manifest
- `GET /v1/guide/patterns` - pattern catalogue (agents)
- `POST /v1/guide/suggest` - rank patterns for an intent
- `GET /v1/guide/capabilities/{chain}` | `GET /v1/guide/guardrails/{chain}` | `GET /v1/guide/limits/{chain}` - chain truth
- `POST /v1/auth/login` - wallet-signature signin (public; mints read-only bearer)
- `POST /v1/auth/email/start` | `POST /v1/auth/email/verify` - email magic-link signin (public; mints read-only bearer)
- `POST /v1/auth/logout` | `GET /v1/auth/whoami` | `POST /v1/auth/rotate` - session (bearer)
- `GET /v1/llm/usage` - measured LLM token counts (admin)
- `GET /v1/billing/shadow` - collected vs owed, mismatches (admin)
- `GET /v1/credits/estimate` - price quote for an endpoint (admin); an exhausted balance is refused with a 402 carrying the typed INSUFFICIENT_CREDITS code
- `POST /v1/payments/watch` - scan a chain and credit confirmed deposits (admin)
- `GET /v1/payments/deposits/{address}` - deposit view for an address (admin)
- `GET /docs` - API reference

## Reading further

The public site is the authority, and it holds the whole public surface:

- https://mintrr.app/ - what mintrr is
- https://mintrr.app/cli.html - visual CLI and optional terminal-workbench overview;
  illustrations are not live sessions or authority to execute
- https://mintrr.app/why.html - why this rather than a coding assistant
- https://mintrr.app/use-cases.html - what people build, by job
- https://mintrr.app/how-it-works.html - the six steps, in plain language
- https://mintrr.app/pricing.html - what costs nothing, what you pay the chain
  directly, and the fee that has no number on it yet
- https://mintrr.app/news.html - templates, features and chains, current as of
  the build that produced it
- https://mintrr.app/blog/ - notes on what it proves and what it refuses
- https://mintrr.app/contact.html - direct email, reasons to get in touch,
  first-message guidance and FAQs
- https://mintrr.app/setup.html - connect an agent in one line (skill + MCP)
- https://mintrr.app/skills/mcp-use.txt - the use-mintrr-well skill: fetch this
  before designing anything, then follow its tool order

The source repository, the internal defect register and the decision records are
private. Nothing in this document depends on them, and no tool can reach them.