@cleave-protocol/ai-sdk 0.1.0 → 0.1.1

package/README.md

@@ -100,6 +100,73 @@ Field-by-field answers are documented at
   the signed order to Cleave's relayer. That second call has
   `needsApproval` set, so the AI SDK asks for your approval before it runs.
 
+## Address checks
+
+Before a `planSwap` plan or a `getGas` offer reaches the model, the package
+checks it against per-chain contract addresses, rails and tokens pinned in
+this package:
+
+- `planSwap`: every call is on the planned chain and from the wallet. The
+  last call goes to a listed contract and function that fits the route,
+  sends to the planned chain and pays the requested recipient where its
+  calldata names one; refunds go to the wallet. Any call before it is an
+  approve of the sell token to that contract for exactly what the last
+  call pulls. For USDC and the chain's native or wrapped native coin, the
+  amount sold is the requested amount. The native value is what the
+  native amount sold and the Stargate native messaging fee need.
+- `getGas`: the authorization is a USDC `ReceiveWithAuthorization` from
+  the wallet on the paying chain. The order carries the requested amount,
+  recipient and refund address, the pinned contracts, rail and fee
+  recipient, and the fee and amounts the offer shows. The order hash and
+  the payment address are recomputed and must match what is signed.
+
+A plan or offer that fails a check is not passed on; the tool returns only
+this:
+
+```json
+{
+  "error": {
+    "code": "address_not_allowed",
+    "message": "P2: the main call's target is not on the allowlist",
+    "retryable": false
+  }
+}
+```
+
+A plan or offer that passes is returned with only its documented
+top-level fields.
+
+What these checks do not cover:
+
+- The price, the route and the amount received.
+- On routes that swap on arrival or pay a fee through the bridge message,
+  the funds go to the Across handler or Cleave's composer, and that
+  message decides who receives them. These checks do not read it, so a
+  compromised API could redirect those funds. Have a person check such a
+  plan before signing.
+- When `sellToken` is a symbol other than USDC or the chain's native or
+  wrapped native coin, the API resolves it to an address. Check
+  `send.token` before signing.
+- For any other sell token, given by symbol or by address, the package
+  does not know its decimals, so the amount in the approve and the
+  calldata is not checked against the request. Check the approve amount
+  and `pullsAtMost` before signing.
+- The Stargate native messaging fee is the API's figure. The checks only
+  match it with the call's value; nothing bounds it.
+- `next` and the notices are text from the API.
+
+After Cleave redeploys a contract, plans that use it fail these checks
+until a package update pins the new address.
+
+Agents that call the API directly should pass each answer through
+`screenPlanSwap(request, body)` or `screenGetGas(request, body)` and use
+only what they return: the refusal, or the answer cut to its documented
+fields. `checkPlanSwap` and `checkGetGas` return only a verdict; a pass
+from them does not make the original answer safe to forward, since it
+can carry fields the checks do not read.
+
+Do not pair these tools with a wallet that signs without a human looking.
+
 ## Gas top-ups
 
 `getGas` takes two calls.
@@ -198,8 +265,9 @@ cleaveTools({
 
 ## Errors
 
-A refusal from the API comes back as the tool's result, unchanged, so the
-model can read it:
+From `planSwap` and `getGas`, a refusal from the API comes back as the
+tool's result with only its `apiVersion`, `requestId` and `error` fields,
+so the model can read it. `trackSwap` and `findToken` return it unchanged:
 
 ```json
 {
@@ -222,7 +290,12 @@ when present, says when.
 
 - a network error, a timeout or an abort: `status` is `0` and `cause`
   holds the original error;
-- an answer that is not JSON: `status` is the HTTP status.
+- a successful answer that is not a JSON object: `status` is the HTTP
+  status.
+
+An error status whose body has no `error` object comes back as the tool's
+result `{ "error": { "code": "http_error", "message": "HTTP 502", "retryable": true } }`,
+with nothing else from the body; `retryable` is true for 5xx and 429.
 
 `requestId` carries the `x-request-id` header when the API sent one.