Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions CANARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,10 @@ lock therefore means a flaw in the contract, the NEAR runtime or the exchange.

### The deployer's upgrade key, and the integrity check

The deployer keeps a full-access key on `vault.intatto.near`, so the funds in this hackathon
deployment stay recoverable. That key can replace the contract's code, and with it any rule above.
The deployer keeps a full-access key on `vault.intatto.near` on purpose: the contract is not audited yet,
and without an upgrade key a bug found later could never be fixed, leaving any funds it affected
stuck for good. Owners withdraw with their own keys, not this one; it is removed after an external
audit. That key can replace the contract's code, and with it any rule above.
Everyone using the vault, the canary included, trusts whoever holds it.

So the canary is tied to a code hash. **If vault.intatto.near's code hash changes, the current
Expand Down Expand Up @@ -252,8 +254,10 @@ lock therefore means a flaw in the contract, the NEAR runtime or the exchange.

### The deployer's upgrade key, and the integrity check

The deployer keeps a full-access key on `vault-v1.intatto-dev.testnet`, so the funds in this
hackathon deployment stay recoverable. That key can replace the contract's code, and with it any
The deployer keeps a full-access key on `vault-v1.intatto-dev.testnet` on purpose: the contract is not audited yet,
and without an upgrade key a bug found later could never be fixed, leaving any funds it affected
stuck for good. Owners withdraw with their own keys, not this one; it is removed after an external
audit. That key can replace the contract's code, and with it any
rule above. Everyone using the vault, the canary included, trusts whoever holds it.

So the canary is tied to a code hash. **If vault-v1's code hash changes, the current canary run
Expand Down
9 changes: 5 additions & 4 deletions CHAIN_SIGNATURES.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
# Chain Signatures intents path (branch `chain-signatures`)
# Chain Signatures intents path

An agent swap through NEAR Intents. The vault's own account on `intents.near` is signed for by
the MPC network (`v1.signer`, domain 1, Ed25519). The agent picks a pair and two amounts. The
vault checks them against the owner's policy, then builds the NEP-413 `token_diff` itself, has
it signed, and settles it by asking `intents.near` whether the nonce was used. Master does not
depend on any of this.
it signed, and settles it by asking `intents.near` whether the nonce was used. The code is in
master (`src/intents.rs`, `src/intent_swap.rs`); the canary's `vault.intatto.near` runs an earlier
build without it.

Invariants 14 to 18 and the trust assumptions (MPC 11-of-16, intents.near governance, the vault
account's full-access key) are in
[THREAT_MODEL.md](THREAT_MODEL.md#chain-signatures-intents-path-branch-chain-signatures-live-on-mainnet).
[THREAT_MODEL.md](THREAT_MODEL.md#chain-signatures-intents-path-live-on-mainnet).

## Live on mainnet, 2026-11-11

Expand Down
116 changes: 116 additions & 0 deletions GTM.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# Intatto: go-to-market plan

Status on 2026-11-13: live on NEAR mainnet (`vault.intatto.near`, `intents.intatto.near`), one
public canary, fee collection proven on mainnet, no outside users yet. This plan says who the first
users are, how they find Intatto, what it costs them, and what we measure. Every number below that
describes the product today links to a transaction or a file; everything else is a target and says
so.

## The problem, for one user

A trading agent needs a key to trade. Today that is the key to its whole wallet: one bug, one
leaked environment file or one prompt injection and the wallet is gone. Intatto gives the agent its
own trading account instead: a vault it can trade from, inside limits the contract enforces, and
can never withdraw from. The agent's key can be stolen and the money stays.

## First customer

**Builders who run trading agents on NEAR today**, with a hot full-access key, through Rhea or NEAR
Intents. Solo developers and small teams running bots for themselves or a few clients.

Why them first:

- They already hold the exact risk Intatto removes, and already trade the venues it supports
(Rhea pools, NEAR Intents).
- Switching costs them almost nothing: their strategy stays the same; only the signer changes, from
a full-access key to a vault-only function-call key.
- They are findable: in the NEAR builder channels, the NEAR AI Agent Market, and the repositories of
this hackathon's agent tracks.

**Second segment: teams putting AI agents in charge of a treasury** (DAOs, agent-run businesses,
payroll and payment agents). Same product, `agent_spend` instead of `agent_swap`, with the receiver
allowlist doing the work.

**Not now:** retail users who want a managed trading bot. Running their agent would mean holding its
key, which is the risk Intatto exists to remove.

## Why they switch

| Today | With Intatto |
|---|---|
| The agent's key can withdraw everything | The key can only call the vault's agent methods; it cannot attach a deposit, so it cannot withdraw ([exact limits](README.md#the-agents-function-call-key-exact-limits)) |
| Limits live in the agent's own code, which the attacker controls | Limits live in the contract: caps per trade and per day, pools, pairs, slippage against the exchange's own quote, price floors |
| A compromised agent is found after the money left | The owner freezes the vault in one call; every refused call is on chain with its reason |
| "Trust our code" | The running code is checked live against its reproducible build, and the agent's key is public on mainnet with real NEAR behind it |

## Distribution, cheapest first

1. **Where agents are built.** The MCP server ([agent/mcp-server.mjs](agent/mcp-server.mjs)) puts the
vault into Claude, ChatGPT, Cursor, Codex and any MCP client as four tools, with a pre-trade
check that blocks bad swaps before they are signed. No package to install: one command adds it.
Next: publish it to npm and to the MCP registries.
2. **The canary as the standing proof.** "The key is public. The money is still here." A live page,
a counter of refused attempts, and a reason for anyone to come and try. Each new refusal is a
post.
3. **NEAR AI Agent Market.** List a reference Intatto trading agent, so agents hired there can
trade with a vault instead of a key.
4. **Build in public on X** from the project account: each mainnet milestone with its transaction
link (first outside vault, first outside attack refused, audit, key removal).
5. **Hand onboarding of design partners.** Ten trading-bot builders, set up one by one, in exchange
for feedback and a public case study.

## Pricing

- **0.10% (10 bps) of the output of every agent swap**, taken by the contract and fixed in its code
([src/fees.rs](src/fees.rs)); no method can change it. Proven on mainnet: the smoke test's swap
[`JAFaEDBh…`](https://nearblocks.io/txns/JAFaEDBhStuPgwgCyNJKU7mQH2K7evjG328zrhudoaC8) paid
0.001887 USDt to the treasury.
- No subscription, no fee on deposits, withdrawals, payments or refused calls.
- Costs, stated plainly: the owner pays the vault's storage (about 0.0015 NEAR to open one) and the
agent pays its own gas (about 0.0036 NEAR per completed swap). The operator's fixed cost is the
contract's storage stake, about 2.55 NEAR ([Unit economics](README.md#unit-economics)). Each new
vault costs the operator nothing per call.
- What it means: at 10 bps, 1,000,000 USD of monthly agent swap volume pays 1,000 USD a month. The
fee only matters at volume, which is why distribution goes where agents are built.

## Launch sequence

| When | What | Done when |
|---|---|---|
| Hackathon (to 2026-11-14) | Mainnet proof: canary, smoke test, intent swap, MCP server, pre-trade check | Live (this repository) |
| Weeks 1 to 4 | Ten design-partner bots onboarded by hand; MCP server on npm | Ten outside vaults with an agent that has traded |
| Weeks 4 to 8 | External audit of the contract | Audit report published |
| After the audit | Both upgrade keys removed; the canary's bounty raised; public launch | `list-keys` shows no full-access key on either vault |
| Next | More Rhea pairs and intent pairs, chosen by liquidity; a reference agent on the Agent Market | Listed |

## What we measure

| Metric | Why |
|---|---|
| Value under policy (all vault balances) | The money that is no longer one key away from gone |
| Agent swap volume, and fee revenue | The business |
| Outside vaults with an agent that has traded | Real adoption, not sign-ups |
| Refused calls, by reason | The product working; each is a loss that did not happen |
| Time from connect to first agent trade | Onboarding; target under 10 minutes |
| Canary attempts, and breaks (target: 0) | The public proof |

All of these are on chain or derived from the vault's own events; the board already shows the
canary's.

## Partners, and what is in it for them

| Partner | Their gain |
|---|---|
| Rhea | Agent swap volume through its pools, from agents that would otherwise not be trusted with keys |
| NEAR Intents | Volume through solvers, signed for the vault by the MPC network |
| NEAR AI | TEE-attested trade decisions recorded on chain with each trade, as a showcase |
| NEAR AI Agent Market | Agents that can be hired to trade without being handed a wallet key |

## Risks

| Risk | Answer |
|---|---|
| A contract bug | The public canary, an external audit before keys are removed, and caps that bound what any bug can lose per day |
| Low trading-agent volume on NEAR | The treasury segment uses the same vault with `agent_spend`; the intents path reaches other chains' assets |
| Copies of the spending-limit idea | Intatto's edges are the trading policy (slippage against the exchange's quote, intent price floors, MPC-signed intents) and the proof (public key on mainnet, reproducible build checked live), not the idea of limits |
| Upgrade keys today | Disclosed in the README and THREAT_MODEL.md, checked live on the board, removed after the audit |
96 changes: 96 additions & 0 deletions INTEGRATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Integrating an agent with Intatto

Three ways to put an agent on an Intatto vault, from least to most code. In all three, the agent
holds a key that can only call the vault's agent methods, and the vault contract enforces the
owner's policy on every call.

## Before you start (the owner, once)

1. Open the owner console at [intatto.pages.dev/#/vault](https://intatto.pages.dev/?network=mainnet#/vault),
connect the owner's wallet and deposit. The console's setup checklist shows each step.
2. Name the agent account and its limits (`set_agent`): per-trade and daily caps per token, the
pools it may use, and the slippage it may accept against the exchange's quote.
3. Give the agent account a function-call key for the vault's agent methods only. **Signs a mainnet
transaction**, with the agent account's own key (near-cli-rs 0.30.1):

```bash
near account add-key <agent-account> grant-function-call-access --allowance '1 NEAR' \
--contract-account-id vault.intatto.near --function-names agent_spend,agent_swap \
autogenerate-new-keypair save-to-legacy-keychain network-config mainnet sign-with-legacy-keychain send
```

The new key's file is the agent's credential. It can trade within the policy; it cannot withdraw
or change the rules.

## 1. From an AI assistant: the MCP server

[agent/mcp-server.mjs](agent/mcp-server.mjs) gives any MCP client (Claude Code, Claude Desktop,
ChatGPT, Cursor, Codex) four tools:

| Tool | What it does | Signs |
|---|---|---|
| `intatto_vault_status` | Balances, freeze, withdrawal lock, policy, and what is left of today's caps | No |
| `intatto_check_agent_key` | Whether the configured key can only call the vault's agent methods | No |
| `intatto_check_swap` | Allow, warn or block for a planned swap, with reasons and a suggested minimum output | No |
| `intatto_swap` | Runs the check, then signs `agent_swap`; refuses on block, needs `acknowledge_warnings` on warn | Only with `INTATTO_ALLOW_TRADES=1` |

Node 22 or later, no packages to install. From a clone of this repository, in Claude Code. Reads
the network when a tool runs; signs only through `intatto_swap` with trades enabled:

```bash
claude mcp add --transport stdio intatto --env INTATTO_NETWORK=mainnet --env INTATTO_VAULT_ID=vault.intatto.near \
--env INTATTO_OWNER_ID=<owner-account> --env INTATTO_AGENT_ID=<agent-account> \
--env INTATTO_AGENT_KEY_FILE=<path-to-agent-key.json> -- node ./Intatto/agent/mcp-server.mjs
```

Other clients take the same command and environment in their MCP configuration. Without
`INTATTO_ALLOW_TRADES=1`, `intatto_swap` returns the exact call it would make and sends nothing;
start that way. The key file stays on your machine: no tool returns it, and the server runs every
output through the same redaction as the demo agent ([agent/secrets.mjs](agent/secrets.mjs)).

The server speaks MCP over stdio in both eras: clients that open with `initialize` (protocol
2025-11-25 and earlier) and clients that send the protocol version on every request (2026-07-28),
with `server/discover`. Tests: [agent/mcp-server.test.mjs](agent/mcp-server.test.mjs).

## 2. From your own agent: the pre-trade check

[agent/risk-check.mjs](agent/risk-check.mjs) is the check the MCP server runs, as a library with no
dependencies. Call it before you sign:

```js
import { Chain } from "./agent/intent-swap.mjs";
import { assessSwap, gatherSwapFacts } from "./agent/risk-check.mjs";

const chain = new Chain("https://rpc.mainnet.fastnear.com/");
const facts = await gatherSwapFacts(chain, {
vaultId: "vault.intatto.near", ownerId, agentId, agentPublicKey,
poolId, tokenIn: "wrap.near", tokenOut: "usdt.tether-token.near",
amountIn: "500000000000000000000000", minAmountOut: "1",
});
// With no minimum of your own, take the check's suggestion: at most 0.5% under the exchange's quote.
const minAmountOut = wanted ?? assessSwap({ ...facts, minAmountOut: "1" }).suggestedMinOut;
const { verdict, reasons } = assessSwap({ ...facts, minAmountOut });
if (verdict === "block") throw new Error(reasons.map((r) => r.message).join(" "));
```

| Verdict | Means |
|---|---|
| `block` | The vault would refuse it (not the agent, frozen, pool or pair not allowed, over a cap or the 24-hour count, slippage past the policy, no quote, not enough balance), or the risk is too high: price impact over 5% against a 1% probe of the same pool, or a signing key that is a full-access key |
| `warn` | It would go through, but: price impact over 1%, a minimum output looser than half the policy's slippage, a cap or count over 80% used, or a token whose account has a full-access key (whoever holds it can replace the token's code) |
| `allow` | None of the above |

The check reads state that can change before the swap lands, so the contract stays the last word:
a swap the check allows can still be refused on chain, with the reason in a `swap_rejected` event.
Tests: [agent/risk-check.test.mjs](agent/risk-check.test.mjs).

## 3. Any signer: call the vault directly

Any code that can sign a NEAR transaction can call `agent_swap` (and `agent_spend`) with the agent's
function-call key. The methods, their arguments and every refusal are in the README's
[Bring your own agent](README.md#bring-your-own-agent). The reference signer, with no dependencies,
is [agent/near-tx.mjs](agent/near-tx.mjs).

## What Intatto does not do

It does not run your agent. If it did, it would hold the agent's key, which is the risk the vault
exists to remove.
Loading
Loading