@parallel-protocol/cli 0.2.11 → 0.3.0

package/README.md

@@ -339,12 +339,17 @@ parallel pay prepare \
 
 # Force which token the agent pays with
 parallel pay prepare --amount <n> --recipient <address> --chain <chain> --pay-with <usdp|usdc|susdp>
+
+# Metered payment (scheme upto): sign --amount as a cap, the merchant charges its actual cost
+parallel pay prepare --amount <cap> --recipient <address> --chain <chain> --scheme upto --valid-for 600 --wallet
 ```
 
 **`--token`** controls what the **merchant receives** (default: `usdp`). Accepted values: `usdp` · `usdc` · `susdp` · any backing collateral symbol (`susds`, `sfrxusd`, …) · a token contract address.
 
 **`--pay-with`** overrides which token the **agent pays with** (default: auto-detected from wallet balance). Accepted values: `usdp` · `usdc` · `susdp`.
 
+**`--scheme`** selects the payment scheme (default: `exact`). With `upto`, `--amount` is a **cap**: the authorization is signed for the cap towards the `UptoEscrow` contract, the merchant settles the amount it actually charges and the escrow refunds the rest to the agent in the same transaction (Route U). Metered payments are USDp only — `--token` and `--pay-with` other than `usdp` are refused. **`--valid-for <seconds>`** (upto only, 1–3600, default 300) sets how long the authorization stays valid; pass the `maxTimeoutSeconds` the merchant announced in its 402. Available on chains where the escrow is deployed (see `parallel pay capabilities`).
+
 **Auto-route selection** (when `--wallet` is provided):
 
 | `--token` (merchant receives) | Agent wallet | Route | Method |
@@ -359,6 +364,7 @@ parallel pay prepare --amount <n> --recipient <address> --chain <chain> --pay-wi
 | `susdp` | sUSDp | J | `transferWithAuthorization` |
 | collateral (e.g. `susds`) | USDp | D | `swapExactOutputWithAuthorization` |
 | collateral (e.g. `susds`) | sUSDp | K | `redeemWithAuthorization` → collateral |
+| `usdp` with `--scheme upto` | USDp ≥ cap | U | `uptoWithAuthorization` (cap signed, actual charged, rest refunded) |
 
 Without `--wallet`, the payload is unsigned and `tokenIn` defaults to `usdp`.
 

package/dist/index.js

@@ -1635,7 +1635,7 @@ function suppressLogs() {
 
 // package.json
 var package_default = {
-  version: "0.2.11"};
+  version: "0.3.0"};
 function findEnvFile(dir) {
   const candidate = join(dir, ".env");
   if (existsSync(candidate)) return candidate;
@@ -1730,7 +1730,8 @@ var CHAINS_STATIC = {
       susdp: "0x472eD57b376fE400259FB28e5C46eB53f0E3e7E7",
       bridgeableUsdp: "0x4Dde0e308CFB60515218C6ad2DF1134Fc48531FC",
       flashParallel: "0x08417cdb7F52a5021bB4eb6E0deAf3f295c3f182",
-      harvester: "0xCa43eCFCDFBA1fED003649e946Ae6091646B410a"
+      harvester: "0xCa43eCFCDFBA1fED003649e946Ae6091646B410a",
+      uptoEscrow: "0xcCA03ed95Ab203a8566a8abfFDF03AEE4030B974"
     }
   },
   arbitrum: {
@@ -1994,6 +1995,9 @@ var PARALLELIZER_CHAINS = CHAIN_NAMES.filter(
 var SAVINGS_CHAINS = CHAIN_NAMES.filter(
   (c) => !!CHAINS_STATIC[c].contracts.susdp
 );
+CHAIN_NAMES.filter(
+  (c) => !!CHAINS_STATIC[c].contracts.uptoEscrow
+);
 function isParallelizerChain(chainName) {
   return !!CHAINS_STATIC[chainName]?.contracts.parallelizer;
 }
@@ -2006,6 +2010,9 @@ function getParallelizerAddress(chainName) {
 function getSUSDpAddress(chainName) {
   return CHAINS_STATIC[chainName]?.contracts.susdp;
 }
+function getUptoEscrowAddress(chainName) {
+  return CHAINS_STATIC[chainName]?.contracts.uptoEscrow;
+}
 var USDC_CHAIN_ADDRESSES = {
   ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
   base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
@@ -5239,6 +5246,35 @@ var SWAP_EXACT_INPUT_TYPEHASH = keccak256(
     "SwapExactInputWithAuthorization(address from,address tokenIn,address tokenOut,uint256 amountIn,uint256 amountOutMin,address to,uint256 deadline,bytes32 userSalt)"
   )
 );
+var UPTO_WITH_AUTHORIZATION_TYPEHASH = keccak256(
+  toHex(
+    "UptoWithAuthorization(address from,address token,uint256 maxAmount,address payTo,uint256 validBefore,bytes32 userSalt)"
+  )
+);
+function deriveUptoNonce(intent) {
+  return keccak256(
+    encodeAbiParameters(
+      [
+        { type: "bytes32" },
+        { type: "address" },
+        { type: "address" },
+        { type: "uint256" },
+        { type: "address" },
+        { type: "uint256" },
+        { type: "bytes32" }
+      ],
+      [
+        UPTO_WITH_AUTHORIZATION_TYPEHASH,
+        intent.from,
+        intent.token,
+        intent.maxAmount,
+        intent.payTo,
+        intent.validBefore,
+        intent.userSalt
+      ]
+    )
+  );
+}
 var REDEEM_WITH_AUTHORIZATION_TYPES = {
   RedeemWithAuthorization: [
     { name: "vault", type: "address" },
@@ -5297,10 +5333,15 @@ var hexBytes = (bytes) => z.string().refine(
 var Bytes32Schema = hexBytes(32);
 var SignatureSchema = hexBytes(65);
 z.object({
+  // Absent means "exact" — the historical wire predates this field.
+  scheme: z.enum(["exact", "upto"]).optional(),
   maxAmountRequired: z.string(),
   asset: AddressSchema,
   payTo: AddressSchema,
-  network: z.string()
+  network: z.string(),
+  // Settlement window (seconds) the merchant grants; drives the payer's
+  // `validBefore`. Absent → the payer's default window applies.
+  maxTimeoutSeconds: z.number().int().positive().optional()
 });
 var AuthorizationSchema = z.object({
   from: AddressSchema,
@@ -5324,6 +5365,9 @@ var DepositAuthorizationSchema = z.object({
   validBefore: z.string(),
   nonce: Bytes32Schema
 });
+var UptoParamsSchema = z.object({
+  payTo: AddressSchema
+});
 var SwapParamsSchema = z.object({
   tokenOut: AddressSchema,
   // swapExactOutput (Routes B/D/I/K): exact collateral out + max USDp in
@@ -5335,7 +5379,7 @@ var SwapParamsSchema = z.object({
   recipient: AddressSchema
 });
 z.object({
-  scheme: z.literal("exact"),
+  scheme: z.enum(["exact", "upto"]),
   network: z.string(),
   method: z.enum([
     "transferWithAuthorization",
@@ -5344,7 +5388,11 @@ z.object({
     "depositWithAuthorization",
     "redeemWithAuthorization",
     // Route L: agent holds USDp + sUSDp, neither sufficient alone.
-    "partialRedeemWithAuthorization"
+    "partialRedeemWithAuthorization",
+    // Scheme upto: ReceiveWithAuthorization(MAX) signed to the UptoEscrow;
+    // the facilitator settles the merchant-decided actual ≤ MAX and the
+    // escrow refunds the remainder atomically.
+    "uptoWithAuthorization"
   ]),
   // Disambiguates routes that share a method but operate on different tokens
   // (e.g. transferWithAuthorization: USDp → A, USDC → F, sUSDp → J). Optional —
@@ -5363,7 +5411,8 @@ z.object({
     // Route G: DepositWithAuthorization signature on the sUSDp domain.
     depositSignature: SignatureSchema.optional()
   }),
-  swapParams: SwapParamsSchema.optional()
+  swapParams: SwapParamsSchema.optional(),
+  uptoParams: UptoParamsSchema.optional()
 });
 var AMOUNT_RE = /^\d{1,30}(\.\d{1,18})?$/;
 var isPlainPositiveDecimal = (v) => AMOUNT_RE.test(v) && parseFloat(v) > 0;
@@ -8578,9 +8627,9 @@ var PREVIEW_MINT_ABI = [
     outputs: [{ type: "uint256" }]
   }
 ];
-function buildTiming() {
+function buildTiming(validitySeconds = 300n) {
   const now = BigInt(Math.floor(Date.now() / 1e3));
-  return { validAfter: now - 60n, validBefore: now + 300n };
+  return { validAfter: now - 60n, validBefore: now + validitySeconds };
 }
 function slippageUp(amount) {
   return amount + amount * SLIPPAGE_BPS / 10000n;
@@ -8788,6 +8837,77 @@ async function prepareRouteA(chain, senderAddress, amount, recipient) {
     gasEstimate: 65e3
   };
 }
+var UPTO_MAX_VALIDITY_SECONDS = 3600;
+async function prepareRouteUpto(chain, senderAddress, maxAmount, recipient, validitySeconds = 300) {
+  const usdpAddress = getUSDpAddress(chain);
+  if (!usdpAddress) throw new Error(`USDp not deployed on ${chain}`);
+  const escrow = getUptoEscrowAddress(chain);
+  if (!escrow) {
+    throw new Error(
+      `[PAYMENT_METHOD_NOT_SUPPORTED] Metered payments (upto) are not available on ${chain}`
+    );
+  }
+  const maxAmountWei = parseUnits(maxAmount, 18);
+  const window2 = BigInt(
+    Math.min(
+      Math.max(1, Math.trunc(validitySeconds)),
+      UPTO_MAX_VALIDITY_SECONDS
+    )
+  );
+  const { validAfter, validBefore } = buildTiming(window2);
+  const userSalt = generateNonce();
+  const derived = deriveUptoNonce({
+    from: senderAddress,
+    token: usdpAddress,
+    maxAmount: maxAmountWei,
+    payTo: recipient,
+    validBefore,
+    userSalt
+  });
+  const authMsg = {
+    from: senderAddress,
+    to: escrow,
+    value: maxAmountWei,
+    validAfter,
+    validBefore,
+    nonce: derived
+  };
+  const domain = await readTokenDomain(chain, usdpAddress);
+  const typedData = buildReceiveAuthorizationTypedData(domain, authMsg);
+  const messageHash = hashTypedData({
+    ...typedData,
+    message: typedData.message
+  });
+  return {
+    route: "U",
+    steps: [
+      {
+        label: "signature",
+        description: "ReceiveWithAuthorization on USDp domain to the UptoEscrow (derived nonce binds payTo and cap)",
+        messageHash,
+        typedData
+      }
+    ],
+    paymentPayload: {
+      scheme: "upto",
+      network: chain,
+      method: "uptoWithAuthorization",
+      payload: {
+        authorization: {
+          from: senderAddress,
+          to: escrow,
+          value: maxAmountWei.toString(),
+          validAfter: validAfter.toString(),
+          validBefore: validBefore.toString(),
+          nonce: userSalt
+        }
+      },
+      uptoParams: { payTo: recipient }
+    },
+    typedData,
+    gasEstimate: 13e4
+  };
+}
 async function prepareRouteB(chain, senderAddress, amount, recipient, targetToken) {
   if (!isParallelizerChain(chain)) {
     throw new Error(
@@ -9714,6 +9834,22 @@ async function preparePayment(params) {
   const sender = params.senderAddress;
   const recv = params.recipient;
   const tokenIn = params.tokenIn ?? "usdp";
+  if (params.scheme === "upto") {
+    const usdp = getUSDpAddress(chain)?.toLowerCase();
+    const wantsOtherToken = params.targetToken !== void 0 && params.targetToken.toLowerCase() !== usdp;
+    if (tokenIn !== "usdp" || wantsOtherToken) {
+      throw new Error(
+        "[PAYMENT_METHOD_NOT_SUPPORTED] Metered payments (upto) are USDp \u2192 USDp only"
+      );
+    }
+    return prepareRouteUpto(
+      chain,
+      sender,
+      amount,
+      recv,
+      params.validitySeconds
+    );
+  }
   const usdpAddress = getUSDpAddress(chain);
   const target = params.targetToken ?? usdpAddress;
   const wantsUSDp = !target || !!usdpAddress && target.toLowerCase() === usdpAddress.toLowerCase();
@@ -10007,6 +10143,13 @@ function prepareCmd() {
   ).option(
     "--pay-with <usdp|usdc|susdp>",
     "force the input token (overrides balance-based auto-selection)"
+  ).option(
+    "--scheme <exact|upto>",
+    "payment scheme: 'upto' signs --amount as a cap settled through the UptoEscrow (USDp only)",
+    "exact"
+  ).option(
+    "--valid-for <seconds>",
+    "upto only: settlement window announced by the merchant (max 3600)"
   ).option(
     "-w, --wallet [path|env]",
     "keystore path or 'env' (PARALLEL_PRIVATE_KEY) \u2014 signs and encodes the payload"
@@ -10029,6 +10172,26 @@ function prepareCmd() {
             `Invalid --pay-with value "${opts.payWith}". Must be one of: usdp, usdc, susdp`
           );
         }
+        if (opts.scheme !== "exact" && opts.scheme !== "upto") {
+          throw new Error(
+            `Invalid --scheme value "${opts.scheme}". Must be one of: exact, upto`
+          );
+        }
+        const isUpto = opts.scheme === "upto";
+        if (isUpto && opts.token.toLowerCase() !== "usdp") {
+          throw new Error(
+            "--scheme upto pays USDp merchants only: use --token usdp"
+          );
+        }
+        if (isUpto && opts.payWith && opts.payWith !== "usdp") {
+          throw new Error(
+            "--scheme upto is paid in USDp: use --pay-with usdp or omit it"
+          );
+        }
+        const validitySeconds = opts.validFor !== void 0 ? assertValidInteger(opts.validFor, "--valid-for", 1, 3600) : void 0;
+        if (!isUpto && validitySeconds !== void 0) {
+          throw new Error("--valid-for only applies to --scheme upto");
+        }
         const account = await loadWallet(walletFlag);
         const senderAddress = account?.address;
         if (!senderAddress && walletFlag) {
@@ -10064,6 +10227,7 @@ function prepareCmd() {
             tokenIn = hasRouteB ? "usdp" : "usdc";
           }
         }
+        if (isUpto) tokenIn = "usdp";
         if (senderAddress) {
           if (tokenIn === "usdp") {
             await assertSufficientBalance(
@@ -10097,7 +10261,9 @@ function prepareCmd() {
           amount: opts.amount,
           recipient: opts.recipient,
           tokenIn,
-          targetToken
+          targetToken,
+          scheme: opts.scheme,
+          validitySeconds
         });
         if (account) {
           const { signedPayload, encoded } = await signPayload(
@@ -10117,8 +10283,12 @@ function prepareCmd() {
               [
                 ["Route", result.route],
                 ["Method", result.paymentPayload.method],
+                ["Scheme", opts.scheme],
                 ["Chain", chain],
-                ["Amount", `${opts.amount} ${tokenLabel2(opts.token)}`],
+                [
+                  isUpto ? "Max Amount" : "Amount",
+                  `${opts.amount} ${tokenLabel2(opts.token)}`
+                ],
                 ["Recipient", opts.recipient],
                 ["Signatures", result.steps.map((s) => s.label).join(", ")],
                 ["Gas Estimate", result.gasEstimate.toLocaleString()]
@@ -15347,7 +15517,7 @@ function swapCommand() {
 
 // ../mcp-server/package.json
 var package_default2 = {
-  version: "1.2.1"};
+  version: "1.3.0"};
 
 // src/commands/version.ts
 function versionCommand() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parallel-protocol/cli",
-	"version": "0.2.11",
+	"version": "0.3.0",
 	"private": false,
 	"type": "module",
 	"files": [