@bananapus/nana-sdk-core 3.3.0 → 3.5.0

package/dist/cjs/v6/pay.d.ts

@@ -121,14 +121,24 @@ export interface PreparedUserPay {
     metadata: Hex;
     preview: PayPreview;
     minReturnedTokens: bigint;
+    /**
+     * True when a pool quote could not be read, even on a retry, so the minimum
+     * is only the mint-based fallback. Show the payer
+     * {@link PAY_QUOTE_FAILED_MESSAGE} and a way to quote again.
+     */
+    quoteFailed?: boolean;
 }
+/** What to tell the payer when {@link PreparedUserPay.quoteFailed} is set. */
+export declare const PAY_QUOTE_FAILED_MESSAGE = "Couldn't read the pool's price, so this payment's minimum is only the mint rate.";
+/** `prepareUserPay`'s tolerance on its quote and fallback minimum: 1%. */
+export declare const PAY_DEFAULT_SLIPPAGE_BPS = 100n;
 /**
  * Prepare a person's payment with {@link buildUserPayMetadata}: preview it,
  * and set the minimum the terminal enforces on the beneficiary's balance.
  *
- * When the project's buyback hook has a pool in the paid token, this quotes
- * that pool (fee and price impact included) and sends the slippage-floored
- * quote as an explicit minimum, so the payer gets the pool's rate whenever it
+ * When the project's buyback hook would swap, this quotes its pool (fee and
+ * price impact included) and sends the slippage-floored quote as an explicit
+ * minimum, so the payer gets the pool's rate whenever it
  * beats minting. The hook compares that minimum to the swap output plus the
  * leftover mint: the whole leftover mint when the swapped tokens go through
  * the reserved split (`skipSplits` false, and always on hook 1.1.1, which
@@ -140,17 +150,34 @@ export interface PreparedUserPay {
  * which reaches zero on large buys against a thin pool and sends them to
  * minting even when the pool pays far more.
  *
- * Otherwise (no pool, a router converting the token first, or a failed quote)
- * the minimum is the payer's mint entitlement when the hook would swap, since
- * the hook never settles below it, and the terminal's own issuance when it
- * would not. If the payment then reverts, {@link decodePayFailure} says why.
+ * Behind a router terminal, its registry or its gateway, when the router
+ * converts the paid token first with one swap, the pool is the one in the
+ * token it converts to, quoted on what that swap is quoted to return. If the
+ * conversion returns noticeably less, the hook's minimum reverts the payment.
+ * If it returns more, the hook mints once minting reaches the minimum, which
+ * happens only when the pool beats minting by less than `slippageBps` plus
+ * that gain. The payer still receives at least the minimum, and no fixed
+ * minimum avoids this when the pool's edge is inside the conversion's
+ * uncertainty. Other routes, such as cashing a project token out first, keep
+ * the fallback. When the project has no buyback hook and accepts one token,
+ * the minimum is what minting the quoted conversion issues, instead of the
+ * router's floor.
+ *
+ * Otherwise (no pool, or a failed quote) the minimum is the payer's mint
+ * entitlement when the hook would swap, since the hook never settles below it,
+ * and the terminal's own issuance when it would not. A quote whose reads fail
+ * twice returns `quoteFailed`, so the app can say the pool's rate is not
+ * protected. If the payment then
+ * reverts, {@link decodePayFailure} says why. To let the payer accept less,
+ * prepare again with a larger `slippageBps`: the hook's minimum is in the
+ * metadata, so lowering `minReturnedTokens` alone does not relax it.
  *
  * When the ruleset calls buyback hook 1.4 directly (or through the omnichain
  * deployer) instead of through the registry, the metadata is keyed to the hook,
  * which reads nothing else.
  *
  * @param args.slippageBps Tolerance on the pool quote and on the fallback
- * minimum. Defaults to 100 (1%).
+ * minimum. Defaults to {@link PAY_DEFAULT_SLIPPAGE_BPS}.
  * @param args.skipSplits Whether the beneficiary keeps the swapped tokens
  * without the reserved split. Defaults to true, as a person's pay card does;
  * pass false for payments that should honor the project's splits, such as

package/dist/cjs/v6/pay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../../src/v6/pay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../../src/v6/pay.ts"],"names":[],"mappings":"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"}