@defuse-protocol/nearintents-mpp-sdk 0.1.0 → 0.1.2

package/README.md

@@ -30,7 +30,7 @@ const mppx = Mppx.create({
 })
 ```
 
-Client (policy is the safety surface — the client pays before delivery):
+Client (`policy` as safety surface, the client pays before delivery):
 
 ```ts
 import { Mppx } from 'mppx/client'
@@ -61,6 +61,27 @@ configured. Without one, the client will pay any authentic challenge the
 server presents; the policy is the client's safety surface since it pays
 before delivery.
 
+## How it works
+
+1. The server answers an unpaid request with `402` + `WWW-Authenticate:
+   Payment` whose `request` carries a unique, single-use **1Click deposit
+   address** as `recipient`, the origin-chain leg the client pays (`amount`,
+   `currency`), and the merchant's destination leg in `methodDetails`.
+2. The client pays the source asset on its origin chain and retries with the
+   confirmed transaction hash as a `{type: "hash"}` credential.
+3. The server verifies the deposit via the 1Click status endpoint, drives the
+   cross-chain swap to `SUCCESS`, and returns the resource with a
+   `Payment-Receipt` carrying `challengeId`, `originTxHash`, and the
+   destination-chain delivery hash.
+
+Quotes use `EXACT_OUTPUT`, so the merchant receives a deterministic amount of
+its chosen asset on its chosen chain. 
+
+Note that settlement is not trustless: deposits are custodied by the NEAR Intents 
+settlement system for the duration of the swap, with automatic refunds 
+to `methodDetails.refundTo` on every non-success outcome. 
+See the spec's Trust Model section.
+
 ## Demo
 
 [`demo/`](demo/README.md) is a browser storefront that runs the real client in
@@ -88,14 +109,13 @@ Arbitrum account and run `pnpm example:client`, or send the deposit yourself
 and re-run with `DEPOSIT_TX_HASH=0x…`. The client refuses anything beyond its
 configured `policy.maxAmountIn` caps.
 
+For operator-only live 1Click smoke testing, `examples/live-oneclick-smoke.ts`
+can be run with `pnpm example:live-oneclick-smoke`. It refuses to contact the
+live provider unless `LIVE_ONE_CLICK=1`, prints deposit instructions in one
+invocation, then polls a separately funded deposit in a second invocation.
+
 ## Operational notes
 
-- **Trust model.** Settlement is not trustless: for the duration of the swap
-  the deposit is custodied by the NEAR Intents settlement system
-  (`methodDetails.settlementBackend: "near-intents"`), which either delivers
-  the destination asset to the merchant or refunds the deposit. Comparable to
-  entrusting a payment processor with a transfer; agents applying per-method
-  risk policies can key off the `method` and `settlementBackend` fields.
 - **Refunds.** `methodDetails.refundTo` is a **merchant-configured** address
   on the origin chain (the server cannot know the payer before payment).
   Every non-success terminal refunds the deposit there; payers recover
@@ -118,10 +138,6 @@ configured `policy.maxAmountIn` caps.
   top-up (that is async-delivery territory, out of scope here). Backend
   aggregation of multiple deposits that reach `SUCCESS` *is* honored: any one
   of the observed origin-chain tx hashes is accepted as the credential.
-- **Per-origin minimums.** Bridged origins enforce minimum deposit amounts
-  (e.g. native BTC rides the PoA bridge, minimum ≈ a few USD at the time of
-  writing — live 1Click rejects quotes below it with `400 Amount is too low
-  for bridge`). Micro-prices belong on fast, cheap origins like Arbitrum/Base.
 - **Slow settlements.** `verify` holds the connection at most
   `settlementTimeout` seconds, then returns **504** with a problem body —
   the credential is *not* consumed and the client re-presents the same
@@ -132,6 +148,12 @@ configured `policy.maxAmountIn` caps.
 - **After a failed settlement** the immediate 402 echoes the spent challenge
   (mppx computes the retry challenge before `verify` runs); the client's next
   request receives a fresh quote. Conformant clients re-request on 402.
+- **Trust model.** Settlement is not trustless: for the duration of the swap
+  the deposit is custodied by the NEAR Intents settlement system
+  (`methodDetails.settlementBackend: "near-intents"`), which either delivers
+  the destination asset to the merchant or refunds the deposit. Comparable to
+  entrusting a payment processor with a transfer; agents applying per-method
+  risk policies can key off the `method` and `settlementBackend` fields.  
 
 ## Observability
 
@@ -154,8 +176,7 @@ mppx.on('payment.failed', ({ error }) => logger.warn(error.type, error.message))
 ```
 
 `settlement.suspended` (backend unavailable / settlement timeout) means the
-credential was **not** consumed and the client will re-present it. Handler
-errors are swallowed — observers can never affect payment processing. The
+credential was **not** consumed and the client will re-present it. The
 example and demo servers wire `onEvent` to the console, so `pnpm
 example:server` shows each payment progressing live. Everything the events
 carry (deposit addresses, tx hashes) is public on-chain data.
@@ -163,7 +184,7 @@ carry (deposit addresses, tx hashes) is public on-chain data.
 ## Advanced: the settlement core
 
 The spec's server steps 7 ("verify deposit") and 8 ("submit + await swap
-finality") are implemented *inside* the method's `verify()` — merchants never
+finality") are implemented *inside* the method's `verify()`. Merchants never
 call them directly, and the safety rails (atomic in-flight hash claim,
 consume-on-terminal, release-on-5xx) live in that sequence. This package uses
 **status observation** (spec §Verification step 3, second mode): 1Click
@@ -177,29 +198,7 @@ tooling), the underlying 1Click client is exported as the `OneClick`
 namespace: `quote`, `submitDeposit`, `getStatus`, `pollToTerminal`,
 `matchesOriginTx`, `destinationTxHash`, `terminalError`, plus the CAIP-19 ↔
 1Click asset mapping (`createAssetMap`). If you drive settlement yourself you
-also own replay protection — prefer re-presenting the credential to the
-method (the 503/504 flow) over hand-rolling steps 7–8.
-
-## How it works
-
-1. The server answers an unpaid request with `402` + `WWW-Authenticate:
-   Payment` whose `request` carries a unique, single-use **1Click deposit
-   address** as `recipient`, the origin-chain leg the client pays (`amount`,
-   `currency`), and the merchant's destination leg in `methodDetails`.
-2. The client pays the source asset on its origin chain and retries with the
-   confirmed transaction hash as a `{type: "hash"}` credential.
-3. The server verifies the deposit via the 1Click status endpoint, drives the
-   cross-chain swap to `SUCCESS`, and returns the resource with a
-   `Payment-Receipt` carrying `challengeId`, `originTxHash`, and the
-   destination-chain delivery hash.
-
-Quotes use `EXACT_OUTPUT`, so the merchant receives a deterministic amount of
-its chosen asset on its chosen chain. 
-
-Note that settlement is not trustless: deposits
-are custodied by the NEAR Intents settlement system for the duration of the
-swap, with automatic refunds to `methodDetails.refundTo` on every non-success
-outcome. See the spec's Trust Model section.
+also own replay protection.
 
 ## Spec
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defuse-protocol/nearintents-mpp-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reference implementation of the `nearintents` payment method for MPP (Machine Payments Protocol) — cross-chain HTTP 402 payments settled by NEAR Intents. Extends mppx.",
   "type": "module",
   "sideEffects": false,
@@ -54,7 +54,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "mppx": "0.8.12",
+    "mppx": "0.8.15",
     "viem": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -66,7 +66,7 @@
     "@biomejs/biome": "^2.5.4",
     "@changesets/cli": "^2.31.1",
     "@types/node": "^26.1.1",
-    "mppx": "0.8.12",
+    "mppx": "0.8.15",
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "viem": "^2.55.4",
@@ -81,6 +81,7 @@
     "demo:build": "pnpm -C demo/app install && pnpm -C demo/app build",
     "demo:server": "tsx --env-file-if-exists=.env demo/server/index.ts",
     "example:client": "tsx --env-file-if-exists=.env examples/client.ts",
+    "example:live-oneclick-smoke": "tsx --env-file-if-exists=.env examples/live-oneclick-smoke.ts",
     "example:server": "tsx --env-file-if-exists=.env examples/server.ts",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",