@saw-protocol/builder

The Execution Plane's transaction builder for the SAWP Protocol.

This module maps strictly validated TransactionIntent objects mathematically into raw, unsigned Solana @solana/web3.js Transactions or VersionedTransactions. It also handles the RPC-heavy lifting: simulation, fee estimation, and robust broadcasting with retries.

Supported Protocols & Operations

The Web3TransactionBuilder currently natively implements translations for the following generic Wallet capabilities:

• transfer: Native SOL token transfers.
• splTransfer: Any SPL Token transfer automatically deriving the Associated Token Accounts.
• swap: Programmatically executing native AMM swaps by interfacing the Jupiter v6 API dynamically.
• stake / unstake: Automating Stake programs generating isolated StakeAccounts and interacting with voting addresses directly.
• liquidity: Represents generalized AMM Provisioning dynamically.

Installation

npm install @saw-protocol/builder

Example Usage

import { Web3TransactionBuilder } from "@saw-protocol/builder";
import { Connection, PublicKey } from "@solana/web3.js";

// Initialize the builder pointing at any standard Solana RPC
const connection = new Connection("https://api.devnet.solana.com");
const builder = new Web3TransactionBuilder({ connection });

const intent = {
  // ... valid TransactionIntent object
  action: {
    type: "swap",
    estimatedValue: 0.1,
    params: {
      inputMint: "So11111111111111111111111111111111111111112",
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: 0.1,
      slippageBps: 50,
    },
  },
};

// 1. Build the raw unsigned Transaction dynamically from the specified Intent
const tx = await builder.build(intent, myWallet);

// 2. Fetch the strict estimated network fee in generic SOL directly from the RPC
const estimatedSolFee = await builder.estimateFee(tx);

// 3. Pre-flight simulate the transaction without actually sending it via the RPC's simulate API
const simResult = await builder.simulate(tx);
if (simResult.success) {
  console.log(
    `Simulation successful. Consumed ${simResult.unitsConsumed} compute units.`,
  );

  // (Assuming the transaction gets securely signed by the Keystore externally right here)

  // 4. Send the explicitly signed transaction. Will block and await confirmation explicitly before returning the Signature.
  const signature = await builder.broadcast(signedTx);
  console.log("Confirmed on-chain:", signature);
} else {
  console.log("Simulation failed due to logical errors:", simResult.error);
}