@stablecoin.xyz/swap-intent 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @stablecoin.xyz/swap-intent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a swap with the SBC Swap API (`swap.stablecoin.xyz`) and check the result against what the user asked for, before signing it. This is the same builder and check the Swap MCP runs; both are built from `mcp/` in [better-intents](https://github.com/stablecoinxyz/better-intents).
+
+```ts
+import { buildSignRequest, decodeEvmRequest, decodeSolRequest, checkIntent } from "@stablecoin.xyz/swap-intent";
+
+// ui: GET/POST against the Swap API (resolves the JSON body, throws on an error status).
+// chain: reads the user's RfqSwap nonce and the input token's EIP-2612 permit nonce from an RPC.
+const req = await buildSignRequest(
+  { ui, chain: { rfqNonce, permitNonce }, net: "mainnet" },
+  { inSym: "SBC", fromChain: "base", outSym: "cfUSD", toChain: "solana", uiAmount: 5, user: myEvmAddress, recipient: mySolAddress },
+);
+
+const evm = req.kind === "sol-tx" ? undefined : decodeEvmRequest(req);
+const sol = req.kind === "sol-tx" ? await decodeSolRequest(req, { loadAlts }) : undefined;
+const verdict = checkIntent({ req, evm, sol, self: { evm: myEvmAddress, sol: mySolAddress }, now: Date.now() });
+if (!verdict.ok) throw new Error(`refusing to sign: ${verdict.reason}`);
+```
+
+`buildSignRequest` refuses a route the API does not list as live in `/api/capabilities`. Always run `checkIntent` on what it returns: the check, not the builder, is what stands between the API's response and the user's signature. `now` is in milliseconds. Gas top-ups also need `minOut`: the gas floor from a fresh `/api/gas/quote` (see `gasFloorOf` and `gasQuoteQuery`); without it they are refused with `gas-floor-missing`.
+
+To follow a cross-chain order, `findOrderOnRails(lookup)` tries each rail in `RAIL` against `GET /api/xchain/status/{orderId}?rail=` and returns the first match. A rail that cannot be read is reported, never read as "no order".
+
+`checkIntent` refuses (`{ ok: false, reason }`) when the transaction pays an unknown token, spender, router, escrow or solver; sends the output anywhere but the user's own wallet; has a deadline or expiry out of bounds; pays less than the quoted floor; or, on Solana, carries extra instructions, an unexpected fee payer or an oversized priority fee.
+
+## Addresses are pinned
+
+Contract addresses, token mints, decimals and the token table are baked into each published version; nothing else from the registry ships. A client must not trust addresses from the same API that built the transaction, so they are never fetched at runtime. When a contract is redeployed, a new version of this package is published, and older versions refuse transactions that use the new addresses.
+
+## Build and publish (maintainers)
+
+```bash
+npm run build:swap-intent        # from the better-intents root
+npm run gate:swap-intent         # the signer suites against the built bundle
+cd packages/swap-intent && npm publish
+```
+
+`prepublishOnly` rebuilds from `mcp/` before every publish. Bump `version` in `packages/swap-intent/package.json` first.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./types/packages/swap-intent/src/index.ts";