@renegade-fi/renegade-sdk 0.1.4 → 0.1.6

package/examples/malleable_external_match.ts

@@ -13,6 +13,7 @@ import type { ExternalOrder } from "../index";
 import { http, createWalletClient } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { arbitrumSepolia } from "viem/chains";
+import type { MalleableExternalMatchResponse } from "../src/types";
 
 // Get API credentials from environment variables
 const API_KEY = process.env.EXTERNAL_MATCH_KEY || "";
@@ -43,7 +44,6 @@ const walletClient = createWalletClient({
 });
 
 // Create the external match client
-console.log("API KEY", API_KEY);
 const client = ExternalMatchClient.newArbitrumSepoliaClient(API_KEY, API_SECRET);
 
 // Example order for USDC/WETH pair
@@ -54,6 +54,71 @@ const order: ExternalOrder = {
     quote_amount: BigInt(20_000_000), // 20 USDC
 };
 
+/**
+ * Set a random base amount on the bundle and print the results
+ * @param bundle The malleable match bundle
+ */
+function setRandomBaseAmount(bundle: MalleableExternalMatchResponse) {
+    // Print bundle info
+    console.log("Bundle info:");
+    const [minBase, maxBase] = bundle.baseBounds();
+    console.log(`Base bounds: ${minBase} - ${maxBase}`);
+
+    // Pick a random base amount and see the send and receive amounts at that base amount
+    const dummyBaseAmount = randomInRange(minBase, maxBase);
+    const dummySendAmount = bundle.sendAmountAtBase(dummyBaseAmount);
+    const dummyReceiveAmount = bundle.receiveAmountAtBase(dummyBaseAmount);
+    console.log(`Hypothetical base amount: ${dummyBaseAmount}`);
+    console.log(`Hypothetical send amount: ${dummySendAmount}`);
+    console.log(`Hypothetical receive amount: ${dummyReceiveAmount}`);
+
+    // Pick an actual base amount to swap with
+    const swappedBaseAmount = randomInRange(minBase, maxBase);
+
+    // Setting the base amount will return the receive amount at the new base
+    // You can also call sendAmount and receiveAmount to get the amounts at the
+    // currently set base amount
+    bundle.setBaseAmount(swappedBaseAmount);
+    const send = bundle.sendAmount();
+    const recv = bundle.receiveAmount();
+    console.log(`Swapped base amount: ${swappedBaseAmount}`);
+    console.log(`Send amount: ${send}`);
+    console.log(`Receive amount: ${recv}`);
+}
+
+/**
+ * Set a random quote amount on the bundle and print the results
+ * @param bundle The malleable match bundle
+ */
+// biome-ignore lint/correctness/noUnusedVariables: User can choose to use this function in the example
+function setRandomQuoteAmount(bundle: MalleableExternalMatchResponse) {
+    // Print bundle info
+    console.log("Bundle info:");
+    const [minQuote, maxQuote] = bundle.quoteBounds();
+    console.log(`Quote bounds: ${minQuote} - ${maxQuote}`);
+
+    // Pick a random base amount and see the send and receive amounts at that base amount
+    const dummyQuoteAmount = randomInRange(minQuote, maxQuote);
+    const dummySendAmount = bundle.sendAmountAtQuote(dummyQuoteAmount);
+    const dummyReceiveAmount = bundle.receiveAmountAtQuote(dummyQuoteAmount);
+    console.log(`Hypothetical quote amount: ${dummyQuoteAmount}`);
+    console.log(`Hypothetical send amount: ${dummySendAmount}`);
+    console.log(`Hypothetical receive amount: ${dummyReceiveAmount}`);
+
+    // Pick an actual base amount to swap with
+    const swappedQuoteAmount = randomInRange(minQuote, maxQuote);
+
+    // Setting the quote amount will return the receive amount at the new quote
+    // You can also call sendAmount and receiveAmount to get the amounts at the
+    // currently set quote amount
+    bundle.setQuoteAmount(swappedQuoteAmount);
+    const send = bundle.sendAmount();
+    const recv = bundle.receiveAmount();
+    console.log(`Swapped quote amount: ${swappedQuoteAmount}`);
+    console.log(`Send amount: ${send}`);
+    console.log(`Receive amount: ${recv}`);
+}
+
 /**
  * Submit a transaction to the chain
  * @param settlementTx The settlement transaction
@@ -93,31 +158,10 @@ async function fullExample() {
             return;
         }
 
-        // Print bundle info
-        console.log("Bundle info:");
-        const [minBase, maxBase] = bundle.baseBounds();
-        console.log(`Base bounds: ${minBase} - ${maxBase}`);
-
-        // Pick a random base amount and see the send and receive amounts at that base amount
-        const dummyBaseAmount = randomInRange(minBase, maxBase);
-        const dummySendAmount = bundle.sendAmountAtBase(dummyBaseAmount);
-        const dummyReceiveAmount = bundle.receiveAmountAtBase(dummyBaseAmount);
-        console.log(`Hypothetical base amount: ${dummyBaseAmount}`);
-        console.log(`Hypothetical send amount: ${dummySendAmount}`);
-        console.log(`Hypothetical receive amount: ${dummyReceiveAmount}`);
-
-        // Pick an actual base amount to swap with
-        const swappedBaseAmount = randomInRange(minBase, maxBase);
-
-        // Setting the base amount will return the receive amount at the new base
-        // You can also call sendAmount and receiveAmount to get the amounts at the
-        // currently set base amount
-        const _recv = bundle.setBaseAmount(swappedBaseAmount);
-        const send = bundle.sendAmount();
-        const recv = bundle.receiveAmount();
-        console.log(`Swapped base amount: ${swappedBaseAmount}`);
-        console.log(`Send amount: ${send}`);
-        console.log(`Receive amount: ${recv}`);
+        // Set a base amount on the bundle
+        // Alternatively, you can set a quote amount on the bundle - see
+        // `setRandomQuoteAmount`
+        setRandomBaseAmount(bundle);
 
         // Step 3: Submit the transaction on-chain
         const txHash = await submitTransaction(bundle.match_bundle.settlement_tx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renegade-fi/renegade-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A TypeScript client for interacting with the Renegade Darkpool API",
   "module": "index.ts",
   "type": "module",

package/src/types/fixedPoint.ts

@@ -12,7 +12,7 @@ export class FixedPoint {
     }
 
     /**
-     * Multiply a fixed point number by a u128 and return the floor
+     * Multiply a fixed point number by a bigint and return the floor
      */
     floorMulInt(amount: bigint): bigint {
         const product = this.value * amount;
@@ -20,4 +20,19 @@ export class FixedPoint {
         const floored = product / FIXED_POINT_PRECISION_SHIFT;
         return floored;
     }
+
+    /**
+     * Divide a bigint by a fixed point number and return the ceiling
+     */
+    static ceilDivInt(amount: bigint, fp: FixedPoint): bigint {
+        const numerator = amount * FIXED_POINT_PRECISION_SHIFT;
+        const quotient = numerator / fp.value;
+        const remainder = numerator % fp.value;
+
+        if (remainder === BigInt(0)) {
+            return quotient;
+        }
+
+        return quotient + BigInt(1);
+    }
 }

package/src/types/malleableMatch.ts

@@ -1,4 +1,4 @@
-import { bytesToHex, concatBytes, hexToBytes, numberToBytes } from "viem/utils";
+import { bytesToHex, concatBytes, hexToBytes, numberToBytes, numberToHex } from "viem/utils";
 import { FixedPoint } from "./fixedPoint";
 import {
     type ApiExternalAssetTransfer,
@@ -8,10 +8,22 @@ import {
     type SettlementTransaction,
 } from "./index";
 
-/** The offset of the base amount in the calldata */
-const BASE_AMOUNT_OFFSET = 4;
-/** The length of the base amount in the calldata */
-const BASE_AMOUNT_LENGTH = 32;
+/** The length of an amount in the calldata, which is 32 bytes for a `uint256` */
+const AMOUNT_CALLDATA_LENGTH = 32;
+/**
+ * The offset of the quote amount in the calldata,
+ * which is `4` because it's the first calldata argument
+ * after the 4-byte function selector
+ */
+const QUOTE_AMOUNT_OFFSET = 4;
+/**
+ * The offset of the base amount in the calldata,
+ * which is `AMOUNT_CALLDATA_LENGTH` bytes after
+ * the quote amount as it is the next calldata argument
+ */
+const BASE_AMOUNT_OFFSET = QUOTE_AMOUNT_OFFSET + AMOUNT_CALLDATA_LENGTH;
+/** The address used to represent the native asset */
+const NATIVE_ASSET_ADDR = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
 
 /**
  * The response type for requesting a malleable quote on an external order
@@ -31,6 +43,17 @@ export class MalleableExternalMatchResponse {
      * consistent
      */
     base_amount?: bigint;
+    /**
+     * The quote amount chosen for the match
+     *
+     * If `undefined`, the quote amount hasn't been selected and defaults to the
+     * quote amount implied by the maximum base amount and the price in the match result.
+     *
+     * This field is not meant for client use directly, rather it is set by
+     * operating on the type and allows the response type to stay internally
+     * consistent
+     */
+    quote_amount?: bigint;
     /**
      * Whether the match was sponsored
      */
@@ -45,11 +68,13 @@ export class MalleableExternalMatchResponse {
         gas_sponsored: boolean,
         gas_sponsorship_info?: GasSponsorshipInfo,
         base_amount?: bigint,
+        quote_amount?: bigint,
     ) {
         this.match_bundle = match_bundle;
         this.gas_sponsored = gas_sponsored;
         this.gas_sponsorship_info = gas_sponsorship_info;
         this.base_amount = base_amount;
+        this.quote_amount = quote_amount;
     }
 
     /**
@@ -60,9 +85,15 @@ export class MalleableExternalMatchResponse {
     public setBaseAmount(baseAmount: bigint) {
         this.checkBaseAmount(baseAmount);
 
+        const impliedQuoteAmount = this.quoteAmount(baseAmount);
+
         // Set the calldata
         this.setBaseAmountCalldata(baseAmount);
+        this.setQuoteAmountCalldata(impliedQuoteAmount);
+
+        // Set the quote and base amounts on the response
         this.base_amount = baseAmount;
+        this.quote_amount = impliedQuoteAmount;
 
         return this.receiveAmount();
     }
@@ -70,20 +101,75 @@ export class MalleableExternalMatchResponse {
     /**
      * Set the calldata to use a given base amount
      */
-    public setBaseAmountCalldata(baseAmount: bigint) {
+    private setBaseAmountCalldata(baseAmount: bigint) {
         const calldataBytes = hexToBytes(this.match_bundle.settlement_tx.data as `0x${string}`);
 
         // Padded to 32 bytes
-        const baseAmountBytes = numberToBytes(baseAmount, { size: BASE_AMOUNT_LENGTH });
+        const baseAmountBytes = numberToBytes(baseAmount, { size: AMOUNT_CALLDATA_LENGTH });
 
         const prefix = calldataBytes.slice(0, BASE_AMOUNT_OFFSET);
         const suffix = calldataBytes.slice(
-            BASE_AMOUNT_OFFSET + BASE_AMOUNT_LENGTH,
+            BASE_AMOUNT_OFFSET + AMOUNT_CALLDATA_LENGTH,
             calldataBytes.length,
         );
 
+        // Set the calldata and the tx value
         const newCalldataBytes = concatBytes([prefix, baseAmountBytes, suffix]);
         const newCalladata = bytesToHex(newCalldataBytes);
+        const value = this.isNativeEthSell() ? baseAmount : 0n;
+        const valueHex = numberToHex(value);
+
+        const newMatchBundle = {
+            ...this.match_bundle,
+            settlement_tx: {
+                ...this.match_bundle.settlement_tx,
+                data: newCalladata,
+                value: valueHex,
+            },
+        };
+
+        this.match_bundle = newMatchBundle;
+    }
+
+    /**
+     * Set the `quote_amount` of the `match_result`
+     *
+     * @returns The amount received at the given `quote_amount`
+     */
+    public setQuoteAmount(quoteAmount: bigint) {
+        const impliedBaseAmount = this.baseAmount(quoteAmount);
+        this.checkQuoteAmount(quoteAmount, impliedBaseAmount);
+
+        // Set the calldata
+        this.setQuoteAmountCalldata(quoteAmount);
+        this.setBaseAmountCalldata(impliedBaseAmount);
+
+        // Set the quote and base amounts on the response
+        this.quote_amount = quoteAmount;
+        this.base_amount = impliedBaseAmount;
+
+        return this.receiveAmount();
+    }
+
+    /**
+     * Set the calldata to use a given quote amount
+     */
+    private setQuoteAmountCalldata(quoteAmount: bigint) {
+        const calldataBytes = hexToBytes(this.match_bundle.settlement_tx.data as `0x${string}`);
+
+        // Padded to 32 bytes
+        const quoteAmountBytes = numberToBytes(quoteAmount, { size: AMOUNT_CALLDATA_LENGTH });
+
+        const prefix = calldataBytes.slice(0, QUOTE_AMOUNT_OFFSET);
+        const suffix = calldataBytes.slice(
+            QUOTE_AMOUNT_OFFSET + AMOUNT_CALLDATA_LENGTH,
+            calldataBytes.length,
+        );
+
+        // Set the calldata and the tx value
+        const newCalldataBytes = concatBytes([prefix, quoteAmountBytes, suffix]);
+        const newCalladata = bytesToHex(newCalldataBytes);
+
         const newMatchBundle = {
             ...this.match_bundle,
             settlement_tx: {
@@ -107,6 +193,41 @@ export class MalleableExternalMatchResponse {
         ];
     }
 
+    /**
+     * Get the bounds on the quote amount
+     *
+     * Returns an array [min, max] inclusive
+     */
+    public quoteBounds(): [bigint, bigint] {
+        const [minBase, maxBase] = this.baseBounds();
+        const price = this.getPriceFp();
+
+        const minQuote = price.floorMulInt(minBase);
+        const maxQuote = price.floorMulInt(maxBase);
+
+        return [minQuote, maxQuote];
+    }
+
+    /**
+     * Get the bounds on the quote amount for a given base amount.
+     *
+     * For an explanation of these bounds, see:
+     * https://github.com/renegade-fi/renegade-contracts/blob/main/contracts-common/src/types/match.rs#L144-L174
+     */
+    public quoteBoundsForBase(baseAmount: bigint): [bigint, bigint] {
+        const [minQuote, maxQuote] = this.quoteBounds();
+
+        const price = this.getPriceFp();
+        const refQuote = price.floorMulInt(baseAmount);
+
+        const direction = this.match_bundle.match_result.direction;
+
+        const resolvedMinQuote = direction === OrderSide.BUY ? refQuote : minQuote;
+        const resolvedMaxQuote = direction === OrderSide.BUY ? maxQuote : refQuote;
+
+        return [resolvedMinQuote, resolvedMaxQuote];
+    }
+
     /**
      * Get the receive amount at the currently set base amount
      */
@@ -121,6 +242,14 @@ export class MalleableExternalMatchResponse {
         return this.computeReceiveAmount(baseAmount);
     }
 
+    /**
+     * Get the receive amount at the given quote amount
+     */
+    public receiveAmountAtQuote(quoteAmount: bigint) {
+        const baseAmount = this.baseAmount(quoteAmount);
+        return this.computeReceiveAmount(baseAmount);
+    }
+
     /**
      * Get the send amount at the currently set base amount
      */
@@ -135,18 +264,54 @@ export class MalleableExternalMatchResponse {
         return this.computeSendAmount(baseAmount);
     }
 
+    /**
+     * Get the send amount at the given quote amount
+     */
+    public sendAmountAtQuote(quoteAmount: bigint) {
+        const baseAmount = this.baseAmount(quoteAmount);
+        return this.computeSendAmount(baseAmount);
+    }
+
+    /**
+     * Return whether the trade is a native ETH sell
+     */
+    public isNativeEthSell(): boolean {
+        const matchRes = this.match_bundle.match_result;
+        const isSell = matchRes.direction === OrderSide.SELL;
+        const isBaseEth = matchRes.base_mint.toLowerCase() === NATIVE_ASSET_ADDR.toLowerCase();
+
+        return isBaseEth && isSell;
+    }
+
     /**
      * Check a base amount is in the valid range
      */
     private checkBaseAmount(baseAmount: bigint) {
-        const min = this.match_bundle.match_result.min_base_amount;
-        const max = this.match_bundle.match_result.max_base_amount;
+        const [min, max] = this.baseBounds();
 
         if (baseAmount < min || baseAmount > max) {
             throw new Error(`Base amount ${baseAmount} is not in the valid range ${min} - ${max}`);
         }
     }
 
+    /**
+     * Check a quote amount is in the valid range for a given base amount.
+     *
+     * This is true if the quote amount is within the bounds implied by the min
+     * and max base amounts given the price in the match results, and the
+     * quote amount does not imply a price improvement over the price in
+     * the match result.
+     */
+    private checkQuoteAmount(quoteAmount: bigint, baseAmount: bigint) {
+        const [min, max] = this.quoteBoundsForBase(baseAmount);
+
+        if (quoteAmount < min || quoteAmount > max) {
+            throw new Error(
+                `Quote amount ${quoteAmount} is not in the valid range ${min} - ${max}`,
+            );
+        }
+    }
+
     /**
      * Get the current receive amount at the given base amount
      *
@@ -183,11 +348,19 @@ export class MalleableExternalMatchResponse {
         return baseAmount;
     }
 
+    /**
+     * Get the base amount at the given quote amount
+     */
+    private baseAmount(quoteAmount: bigint) {
+        const price = this.getPriceFp();
+        return FixedPoint.ceilDivInt(quoteAmount, price);
+    }
+
     /**
      * Get the quote amount at the given base amount
      */
     private quoteAmount(baseAmount: bigint) {
-        const price = new FixedPoint(BigInt(this.match_bundle.match_result.price_fp));
+        const price = this.getPriceFp();
         return price.floorMulInt(baseAmount);
     }
 
@@ -200,6 +373,10 @@ export class MalleableExternalMatchResponse {
         }
         return this.base_amount;
     }
+
+    private getPriceFp() {
+        return new FixedPoint(BigInt(this.match_bundle.match_result.price_fp));
+    }
 }
 
 /**

package/src/version.ts

@@ -1,7 +1,7 @@
 /**
  * SDK version information
  * This file is automatically updated during the build process
- * Last updated: 2025-05-08T00:25:05Z
+ * Last updated: 2025-05-21T22:43:53Z
  */
 
-export const VERSION = '0.1.4';
+export const VERSION = '0.1.6';