@renegade-fi/renegade-sdk 0.1.5 → 0.1.7

package/examples/base_sepolia_match.ts

@@ -0,0 +1,117 @@
+/**
+ * Basic example of using the Renegade External Match Client
+ *
+ * This example demonstrates how to create a client, request a quote, assemble a match, and submit the transaction on-chain.
+ */
+
+import { ExternalMatchClient, OrderSide } from "../index";
+import type { ExternalOrder } from "../index";
+
+// Viem imports for on-chain transactions
+import { http, createWalletClient } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+
+// Get API credentials from environment variables
+const API_KEY = process.env.EXTERNAL_MATCH_KEY || "";
+const API_SECRET = process.env.EXTERNAL_MATCH_SECRET || "";
+const PRIVATE_KEY = process.env.PKEY || "";
+const RPC_URL = process.env.RPC_URL || "https://sepolia.base.org";
+
+// Validate API credentials
+if (!API_KEY || !API_SECRET) {
+    console.error("Error: Missing API credentials");
+    console.error("Please set EXTERNAL_MATCH_KEY and EXTERNAL_MATCH_SECRET environment variables");
+    process.exit(1);
+}
+
+// Validate wallet private key
+if (!PRIVATE_KEY) {
+    console.error("Error: Missing private key");
+    console.error("Please set PKEY environment variable");
+    process.exit(1);
+}
+
+// Set up wallet client for blockchain transactions
+const privateKey = PRIVATE_KEY.startsWith("0x") ? PRIVATE_KEY : `0x${PRIVATE_KEY}`;
+const walletClient = createWalletClient({
+    account: privateKeyToAccount(privateKey as `0x${string}`),
+    chain: baseSepolia,
+    transport: http(RPC_URL),
+});
+
+// Create the external match client
+console.log("API KEY", API_KEY);
+const client = ExternalMatchClient.newBaseSepoliaClient(API_KEY, API_SECRET);
+
+// Example order for USDC/WETH pair
+const order: ExternalOrder = {
+    quote_mint: "0xD9961Bb4Cb27192f8dAd20a662be081f546b0E74", // USDC on testnet
+    base_mint: "0xb51a558c8E55DE1EE5391BDFe2aFA49968FC3B25", // cbBTC on testnet
+    side: OrderSide.BUY,
+    quote_amount: BigInt(20_000_000), // 20 USDC
+};
+
+/**
+ * Submit a transaction to the chain
+ * @param settlementTx The settlement transaction
+ * @returns The transaction hash
+ */
+async function submitTransaction(settlementTx: any): Promise<`0x${string}`> {
+    console.log("Submitting transaction...");
+
+    const tx = await walletClient.sendTransaction({
+        to: settlementTx.to as `0x${string}`,
+        data: settlementTx.data as `0x${string}`,
+        value: settlementTx.value ? BigInt(settlementTx.value) : BigInt(0),
+    });
+
+    return tx;
+}
+
+// Full example with on-chain submission
+async function fullExample() {
+    try {
+        // Step 1: Request a quote
+        console.log("Requesting quote...");
+        const quote = await client.requestQuote(order);
+
+        if (!quote) {
+            console.log("No quote available");
+            return;
+        }
+
+        console.log("Quote received!");
+
+        // Step 2: Assemble the quote into a match bundle
+        console.log("Assembling match...");
+        const bundle = await client.assembleQuote(quote);
+
+        if (!bundle) {
+            console.log("No match available");
+            return;
+        }
+
+        console.log("Match assembled!");
+
+        // Step 3: Submit the transaction on-chain
+        const txHash = await submitTransaction(bundle.match_bundle.settlement_tx);
+        console.log(
+            "Transaction submitted:",
+            `${walletClient.chain.blockExplorers?.default.url}/tx/${txHash}`,
+        );
+    } catch (error) {
+        console.error("Error:", error);
+    }
+}
+
+// Run the examples
+async function main() {
+    console.log("Running full example with on-chain submission...");
+    await fullExample();
+}
+
+// Only run if this file is being executed directly
+if (require.main === module) {
+    main().catch(console.error);
+}

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 || "";
@@ -53,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
@@ -92,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.5",
+  "version": "0.1.7",
   "description": "A TypeScript client for interacting with the Renegade Darkpool API",
   "module": "index.ts",
   "type": "module",

package/src/client.ts

@@ -22,6 +22,8 @@ import { VERSION } from "./version";
 // Constants for API URLs
 const ARBITRUM_SEPOLIA_BASE_URL = "https://arbitrum-sepolia.auth-server.renegade.fi";
 const ARBITRUM_ONE_BASE_URL = "https://arbitrum-one.auth-server.renegade.fi";
+const BASE_SEPOLIA_BASE_URL = "https://base-sepolia.auth-server.renegade.fi";
+const BASE_MAINNET_BASE_URL = "https://base-mainnet.auth-server.renegade.fi";
 
 // Header constants
 const RENEGADE_API_KEY_HEADER = "x-renegade-api-key";
@@ -290,6 +292,17 @@ export class ExternalMatchClient {
         return new ExternalMatchClient(apiKey, apiSecret, ARBITRUM_SEPOLIA_BASE_URL);
     }
 
+    /**
+     * Create a new client configured for the Base Sepolia testnet.
+     *
+     * @param apiKey The API key for authentication
+     * @param apiSecret The API secret for request signing
+     * @returns A new ExternalMatchClient configured for Sepolia
+     */
+    static newBaseSepoliaClient(apiKey: string, apiSecret: string): ExternalMatchClient {
+        return new ExternalMatchClient(apiKey, apiSecret, BASE_SEPOLIA_BASE_URL);
+    }
+
     /**
      * Create a new client configured for the Arbitrum One mainnet.
      *
@@ -310,6 +323,17 @@ export class ExternalMatchClient {
         return new ExternalMatchClient(apiKey, apiSecret, ARBITRUM_ONE_BASE_URL);
     }
 
+    /**
+     * Create a new client configured for the Base mainnet.
+     *
+     * @param apiKey The API key for authentication
+     * @param apiSecret The API secret for request signing
+     * @returns A new ExternalMatchClient configured for mainnet
+     */
+    static newBaseMainnetClient(apiKey: string, apiSecret: string): ExternalMatchClient {
+        return new ExternalMatchClient(apiKey, apiSecret, BASE_MAINNET_BASE_URL);
+    }
+
     /**
      * Request a quote for the given order.
      *

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

@@ -8,10 +8,20 @@ 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";
 
@@ -33,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
      */
@@ -47,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;
     }
 
     /**
@@ -62,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();
     }
@@ -72,18 +101,19 @@ 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;
@@ -101,6 +131,56 @@ export class MalleableExternalMatchResponse {
         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: {
+                ...this.match_bundle.settlement_tx,
+                data: newCalladata,
+            },
+        };
+
+        this.match_bundle = newMatchBundle;
+    }
+
     /**
      * Get the bounds on the base amount
      *
@@ -113,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
      */
@@ -127,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
      */
@@ -141,6 +264,14 @@ 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
      */
@@ -156,14 +287,31 @@ export class MalleableExternalMatchResponse {
      * 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
      *
@@ -200,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);
     }
 
@@ -217,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-10T01:06:48Z
+ * Last updated: 2025-05-30T00:51:32Z
  */
 
-export const VERSION = '0.1.5';
+export const VERSION = '0.1.7';