Sanctum Gateway

https://gateway.sanctum.so/docs
Admin
Sanctum Gateway is a high-performance API and dashboard designed to optimize, send, and observe...
Tokens:9,840
Snippets:41
Trust Score:8.2
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get and Send Transaction with Tip Instructions (TypeScript)

Source: https://gateway.sanctum.so/docs/concepts/builder

This snippet demonstrates how to use the `getTipInstructions` method to fetch transaction tip instructions based on delivery method. It then constructs a Solana transaction using these instructions along with compute budget settings, a SOL transfer, and signs it using provided keypairs. Finally, it sends the signed transaction using the Gateway API. Dependencies include `@solana/kit` and `@solana-program/compute-budget`.

```typescript
import {
  appendTransactionMessageInstructions,
  compileTransaction,
  createSolanaRpc,
  createTransactionMessage,
  getBase64EncodedWireTransaction,
  type IInstruction,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransaction,
} from "@solana/kit";
import {
  getSetComputeUnitLimitInstruction,
  getSetComputeUnitPriceInstruction,
} from "@solana-program/compute-budget";
import { getTransferSolInstruction } from "@solana-program/system";
import { getAccounts, getTritonPrioritizationFees } from "./utils.js";

export const GATEWAY_ENDPOINT = `https://tpg.sanctum.so/v1/mainnet?apiKey=${process.env.GATEWAY_API_KEY}`;

// Random source and destination used for example
const { alice, bob } = await getAccounts();

const rpc = createSolanaRpc(process.env.RPC_URL as string);

const transferIx = getTransferSolInstruction({
  source: alice,
  destination: bob,
  amount: 1000n,
});

// Fetch latest blockhash, CU price and getTipInstructions response
const [{ value: latestBlockhash }, cuPrice, getTipInstructionsResponse] =
  await Promise.all([
    rpc.getLatestBlockhash().send(),
    getTritonPrioritizationFees([alice.address, bob]),
    fetch(GATEWAY_ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        id: "demo",
        jsonrpc: "2.0",
        method: "getTipInstructions",
        params: [
          {
            feePayer: alice.address,
            // jitoTipRange: "low" | "medium" | "high" | "max", defaults to project parameters
            // deliveryMethodType: "rpc" | "jito" | "sanctum-sender" | "helius-sender", defaults to project parameters
          },
        ],
      }),
    }),
  ]);

if (!getTipInstructionsResponse.ok) {
  throw new Error("Failed to get tip instructions");
}

// Parse tip instructions response and convert to Instruction[]
const tipIxs: IInstruction[] = [];
const tipIxsData = await getTipInstructionsResponse.json();
for (const ix of tipIxsData.result) {
  tipIxs.push({
    ...ix,
    data: new Uint8Array(Object.values(ix.data)),
  });
}

// Hardcode CU limit, but you can also simulate the transaction to get the exact CU limit
const cuLimitIx = getSetComputeUnitLimitInstruction({
  units: 800,
});

const cuPriceIx = getSetComputeUnitPriceInstruction({
  microLamports: cuPrice,
});

const transaction = pipe(
  createTransactionMessage({ version: 0 }),
  (txm) =>
    appendTransactionMessageInstructions(
      [cuLimitIx, cuPriceIx, transferIx, ...tipIxs],
      txm
    ),
  (txm) => setTransactionMessageFeePayerSigner(alice, txm),
  (m) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
  compileTransaction
);

const signedTransaction = await signTransaction([alice.keyPair], transaction);

const sendTransactionResponse = await fetch(GATEWAY_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "demo",
    jsonrpc: "2.0",
    method: "sendTransaction",
    params: [getBase64EncodedWireTransaction(signedTransaction)],
  }),
});

if (!sendTransactionResponse.ok) {
  throw new Error("Failed to send transaction");
}

const data = await sendTransactionResponse.json();

console.log(data);

```

--------------------------------

### Request Example for Optimizing Transactions

Source: https://gateway.sanctum.so/docs/concepts/optimization

This snippet demonstrates how to send a POST request to the Gateway API to optimize a transaction. It includes the `optimizeTransaction` method and optional parameters for CU price range, Jito tip range, and expiry. The transaction is expected to be base64 encoded.

```typescript
import { getBase64EncodedWireTransaction } from "@solana/kit";

const optimizeResponse = await fetch(`${GATEWAY_URL}/mainnet?apiKey=${apiKey}`, {
  method: 'POST',
  body: JSON.stringify({
    id: "test-id",
    jsonrpc: "2.0",
    method: "optimizeTransaction",
    params: {
      transactions: [
        {
          params: [
            getBase64EncodedWireTransaction(tx),
            // Optionally override the Project Configuration
            { cuPriceRange: "high", jitoTipRange: "high", expireInSlots: 5, encoding: "base64" }
          ],
        },
      ],
    }
  }),
  headers: {'Content-Type': 'application/json'}
});

```

--------------------------------

### Gateway Send Transaction JSON Response Example

Source: https://gateway.sanctum.so/docs/concepts/delivery

An example of a JSON response from the Gateway API when sending a transaction. It follows the JSON-RPC 2.0 specification, including an `id` and either a `result` containing the transaction signature or an `error` object detailing the failure.

```json
{
  "jsonrpc": "2.0",
  "id": "test-id",
  "result": "E7oKpwds2h4xxcrGoccrizTEVWvgu6k8u..."
}
```

--------------------------------

### Optimize Solana Transactions with Gateway and Jito Tips (TypeScript)

Source: https://gateway.sanctum.so/docs/concepts/optimization

This TypeScript code demonstrates how to set up transactions for self-optimization using Gateway and Jito. It includes steps for simulating the transaction to determine CU limits, calculating Gateway and Jito tips based on priority fees, and appending these tips as instructions to the transaction message before compiling and encoding it for delivery.

```typescript
import { getTransferSolInstruction } from "@solana-program/system";
import {
  pipe,
  address,
  createSolanaRpc,
  createTransactionMessage,
  getBase64EncodedWireTransaction,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  createKeyPairSignerFromBytes,
  compileTransaction,
  appendTransactionMessageInstruction
} from "@solana/kit";

// 150 for each of the transfer, cuLimit, and cuPrice instructions
const EXTRA_CU_CONSUMED = 150 + 150 + 150;

const TIP_DESTINATIONS = [...]; // Found at Misc/Tip-Accounts
const tipDestination = TIP_DESTINATIONS[
	Math.floor(Math.random() * TIP_DESTINATIONS.length)
];

function getGatewayTip(cuPrice: bigint, cuLimit: bigint) {
  // 25% of priority fee
  const priorityFeeMicroLamports = cuPrice * cuLimit;
  const gatewayFeeMicroLamports = (priorityFeeMicroLamports * 25n) / 100n;
  const gatewayFeeLamports = Math.round(Number(gatewayFeeMicroLamports) / 1_000_000);
  return BigInt(gatewayFeeLamports);
}

// Replace with your own values
const feePayer = await createKeyPairSignerFromBytes(new Uint8Array());
const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");

const initialMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(feePayer.address, m),
  (m) =>
    setTransactionMessageLifetimeUsingBlockhash(
      {
        blockhash: (await rpc.getLatestBlockhash().send()).value.blockhash,
        lastValidBlockHeight: 1000n,
      },
      m
    ),
  // Your instructions here
);

const initialTx = await compileTransaction(initialMessage);

const simulation = await rpc.simulateTransaction(
  getBase64EncodedWireTransaction(initialTx), {
    encoding: "base64",
    sigVerify: false,
  }
).send();

if (simulation.value.unitsConsumed === undefined) {
  throw new Error("Simulation failed");
}

// Derived from the tx simulation
const txCuLimit = BigInt(simulation.value.unitsConsumed) + BigInt(EXTRA_CU_CONSUMED);
// Fetch from a Priority Fee API of your choice, Helius, Triton etc.
const txCuPrice = BigInt(...);

const gatewayTip = getGatewayTip(txCuPrice, txCuLimit);

// Fetch from Jito Tip Floor API if using Jito Bundles
const jitoTipFloor = BigInt(...);
const totalTip = gatewayTip + jitoTipFloor;

// Add this tip instruction to the transaction
const tipIx = getTransferSolInstruction({
  source: feePayer,
  destination: address(tipDestination),
  amount: totalTip,
});

const preparedTxForDelivery = pipe(
  initialMessage,
  (m) => appendTransactionMessageInstruction(tipIx, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(
    {
      blockhash: (await rpc.getLatestBlockhash().send()).value.blockhash,
      lastValidBlockHeight: 1000n,
    },
    m
  ),
  compileTransaction,
);

// Use this encoded transaction with `sendOptimizedTransaction` method
const encodedTx = getBase64EncodedWireTransaction(preparedTxForDelivery);

```

--------------------------------

### Build Gateway Transaction using TypeScript

Source: https://gateway.sanctum.so/docs/concepts/builder

This TypeScript snippet demonstrates how to use the `buildGatewayTransaction` method to prepare a Solana transaction for sending via Gateway. It includes simulating the transaction, fetching prioritization fees, adding tip instructions, and setting blockhash. It uses `@solana/kit` for transaction manipulation and `fetch` for the JSON-RPC call. Ensure your `GATEWAY_API_KEY` is set in the environment variables.

```typescript
import {
  appendTransactionMessageInstructions,
  blockhash,
  compileTransaction,
  createTransactionMessage,
  getBase64EncodedWireTransaction,
  getBase64Encoder,
  getTransactionDecoder,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransaction,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";

export const GATEWAY_ENDPOINT = `https://tpg.sanctum.so/v1/mainnet?apiKey=${process.env.GATEWAY_API_KEY}`;

// Random source and destination used for example
const { alice, bob } = await getAccounts();

const transferIx = getTransferSolInstruction({
  source: alice,
  destination: bob,
  amount: 1000n,
});

const unsignedTransaction = pipe(
  createTransactionMessage({ version: 0 }),
  (txm) => appendTransactionMessageInstructions([transferIx], txm),
  (txm) => setTransactionMessageFeePayerSigner(alice, txm),
  // Since `buildGatewayTransaction` will set the blockhash for you,
  // We can avoid fetching the latest blockhash here
  (m) =>
    setTransactionMessageLifetimeUsingBlockhash(
      {
        blockhash: blockhash("11111111111111111111111111111111"),
        lastValidBlockHeight: 1000n,
      },
      m
    ),
  compileTransaction
);

const buildGatewayTransactionResponse = await fetch(GATEWAY_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "startup-village",
    jsonrpc: "2.0",
    method: "buildGatewayTransaction",
    params: [
      getBase64EncodedWireTransaction(unsignedTransaction),
      {
        // encoding: "base64" | "base58", default is "base64"
        // skipSimulation: boolean, if true, you need to set the CU limit yourself since simulation allows to find out cu consumed.
        // skipPriorityFee: boolean, if true, you need to set the CU price yourself. Use Triton Priority Fee API
        // cuPriceRange: "low" | "medium" | "high", defaults to project parameters
        // jitoTipRange: "low" | "medium" | "high" | "max", defaults to project parameters
        // expireInSlots: number, defaults to project parameters
        // deliveryMethodType: "rpc" | "jito" | "sanctum-sender" | "helius-sender", defaults to project parameters
      },
    ],
  }),
});

if (!buildGatewayTransactionResponse.ok) {
  throw new Error("Failed to build gateway transaction");
}

const { 
  result: { transaction: encodedTransaction },
} = (await buildGatewayTransactionResponse.json()) as {
  result: {
    transaction: string;
    latestBlockhash: {
      blockhash: string;
      lastValidBlockHeight: string;
    };
  };
};

const transaction = getTransactionDecoder()
  .decode(getBase64Encoder().encode(encodedTransaction));

const signedTransaction = await signTransaction([alice.keyPair], transaction);

const sendTransactionResponse = await fetch(GATEWAY_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "startup-village",
    jsonrpc: "2.0",
    method: "sendTransaction",
    params: [getBase64EncodedWireTransaction(signedTransaction)],
  }),
});

if (!sendTransactionResponse.ok) {
  throw new Error("Failed to send transaction");
}

const data = await sendTransactionResponse.json();

console.log(data);

```

--------------------------------

### Send Solana Transaction via Gateway API (TypeScript)

Source: https://gateway.sanctum.so/docs/concepts/delivery

This snippet demonstrates how to send an optimized and signed Solana transaction using the Gateway API. It involves decoding, signing, and then posting the transaction to the `/v1/mainnet` endpoint. Ensure you have the necessary API key and the `GATEWAY_URL` configured. The `startSlot` parameter is optional for more precise latency tracking.

```typescript
import {
  getBase64Encoder,
  getTransactionDecoder,
  getBase64EncodedWireTransaction
} from "@solana/kit";

// Continued from `buildGatewayTransaction`...
const optimizedTxString = optimizeBody.result.transaction;
const optimizedTx = getTransactionDecoder()
    .decode(getBase64Encoder().encode(optimizedTxString));

const signedTx = await signTransaction([keyPair], optimizedTx);

const deliveryResponse = await fetch(`${GATEWAY_URL}/v1/mainnet?apiKey=${apiKey}`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'}
  body: JSON.stringify({
    id: "test-id",
    jsonrpc: "2.0",
    method: "sendTransaction",
    params: [getBase64EncodedWireTransaction(signedTx), {
        encoding: "base64",
		startSlot: 361082604
    }]
  }),
});
```

--------------------------------

### Build Transaction Request - TypeScript

Source: https://gateway.sanctum.so/docs/endpoints

Demonstrates how to construct a POST request to the TPG endpoint to build a gateway transaction. It includes setting the correct URL, headers, and request body.

```typescript
const response = await fetch('https://tpg.sanctum.so/v1/mainnet?apiKey=your-api-key', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    method: 'buildGatewayTransaction',
    params: [getBase64EncodedWireTransaction(transaction)],
  })
});
```

--------------------------------

### Builder API - buildGatewayTransaction

Source: https://gateway.sanctum.so/docs/concepts/builder

The `buildGatewayTransaction` method accepts an existing transaction and returns an updated transaction ready to be sent to Gateway. It can be used to simulate transactions, fetch prioritization fees, add tip instructions, and set the `latestBlockhash`.

```APIDOC
## POST /v1/mainnet

### Description
Builds a Gateway transaction by simulating it, fetching prioritization fees, adding tip instructions, and setting the latest blockhash.

### Method
POST

### Endpoint
`/v1/mainnet`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.

#### Request Body
- **id** (string) - Required - A unique identifier for the request.
- **jsonrpc** (string) - Required - The JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method to call, must be "buildGatewayTransaction".
- **params** (array) - Required - An array containing the transaction and build options.
  - **params[0]** (string) - Required - The base64 encoded wire transaction.
  - **params[1]** (object) - Optional - Options for building the transaction:
    - **encoding** (string) - Optional - "base64" or "base58", defaults to "base64".
    - **skipSimulation** (boolean) - Optional - If true, skips simulation. CU limit must be set manually.
    - **skipPriorityFee** (boolean) - Optional - If true, skips priority fee fetching. CU price must be set manually.
    - **cuPriceRange** (string) - Optional - "low", "medium", or "high", defaults to project parameters.
    - **jitoTipRange** (string) - Optional - "low", "medium", "high", or "max", defaults to project parameters.
    - **expireInSlots** (number) - Optional - Defaults to project parameters.
    - **deliveryMethodType** (string) - Optional - "rpc", "jito", "sanctum-sender", or "helius-sender", defaults to project parameters.

### Request Example
```json
{
  "id": "startup-village",
  "jsonrpc": "2.0",
  "method": "buildGatewayTransaction",
  "params": [
    "BASE64_ENCODED_TRANSACTION",
    {
      "skipSimulation": false,
      "cuPriceRange": "medium"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the result of the build operation.
  - **transaction** (string) - The base64 encoded wire transaction, ready to be sent.
  - **latestBlockhash** (object) - Information about the latest blockhash.
    - **blockhash** (string) - The latest blockhash.
    - **lastValidBlockHeight** (string) - The height of the last valid block.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction": "BASE64_ENCODED_UPDATED_TRANSACTION",
    "latestBlockhash": {
      "blockhash": "EjwzUuE1887zF7pM5z23F4h2vB5y7t8d5X7v7f8d3",
      "lastValidBlockHeight": "123456789"
    }
  },
  "id": "startup-village"
}
```

#### Error Response
- **error** (object) - Contains error details if the request failed.
  - **code** (number) - The error code.
  - **message** (string) - The error message.
  - **data** (any) - Optional additional error data.
```
```

--------------------------------

### Processing Optimized Transaction Response

Source: https://gateway.sanctum.so/docs/concepts/optimization

This TypeScript code illustrates how to parse the response from the transaction optimization endpoint. It extracts the base64 encoded optimized transaction and the latest blockhash, then decodes and prepares the transaction for signing using `@solana/kit`.

```typescript
import {
  signTransaction,
  getBase64Encoder,
  getTransactionDecoder
} from "@solana/kit";

const optimizeBody = await optimizeResponse.json();
const optimizedTxString = optimizeBody.result[0].transaction;
const latestBlockhash = optimizeBody.result[0].latestBlockhash;

// Decode and sign the optimized transaction
const optimizedTx = getTransactionDecoder()
    .decode(getBase64Encoder().encode(optimizedTxString));

const signedTx = await signTransaction([keyPair], optimizedTx);

// The latestBlockhash can be used later to verify transaction confirmation
// blockhash: latestBlockhash.blockhash
// lastValidBlockHeight: Number(latestBlockhash.lastValidBlockHeight)

```

--------------------------------

### Send Transaction

Source: https://gateway.sanctum.so/docs/concepts/delivery

Send a transaction using the `sendTransaction` method through the Gateway API. This method routes the transaction across chosen delivery methods and records slot latency.

```APIDOC
## POST /v1/mainnet

### Description
Sends a transaction through the Gateway API, supporting simultaneous delivery across multiple methods for increased success rates. It also allows for tracking slot latency by optionally including a `startSlot`.

### Method
POST

### Endpoint
`/v1/mainnet?apiKey=<YOUR_API_KEY>`

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.

#### Request Body
- **id** (string) - Required - A unique identifier for the request.
- **jsonrpc** (string) - Required - The JSON-RPC version, typically "2.0".
- **method** (string) - Required - The method to call, which is "sendTransaction".
- **params** (array) - Required - An array containing the transaction and optional parameters.
  - **param1** (string) - Required - The wire transaction encoded in `base64` or `base58`.
  - **param2** (object) - Optional - Additional parameters for the transaction.
    - **encoding** (string) - Required - The encoding format of the transaction, either `base64` or `base58`.
    - **startSlot** (number) - Optional - The slot at which the transaction starts, used for precise end-to-end latency tracking.

### Request Example
```typescript
{
  "id": "test-id",
  "jsonrpc": "2.0",
  "method": "sendTransaction",
  "params": [
    "<base64_encoded_wire_transaction>",
    {
      "encoding": "base64",
      "startSlot": 361082604
    }
  ]
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (string) - The identifier for the request.
- **result** (string) - The transaction signature if successful.

#### Error Response
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (string) - The identifier for the request.
- **error** (object) - An object containing error details.
  - **code** (number) - The error code.
  - **message** (string) - A message describing the error.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "test-id",
  "result": "E7oKpwds2h4xxcrGoccrizTEVWvgu6k8u..."
}
```
```

--------------------------------

### Gateway Delivery Response Structure (TypeScript)

Source: https://gateway.sanctum.so/docs/concepts/delivery

Defines the TypeScript interface for the response received from the Gateway API after sending a transaction. The response indicates success with a transaction signature in the `result` field or failure with an error code and message in the `error` field.

```typescript
type DeliveryResult = {
  result?: string; // Transaction signature
  error?: {
    code: number,
	message: string
  }
};
```

--------------------------------

### Gateway Transaction Processing API

Source: https://gateway.sanctum.so/docs/endpoints

The Transaction Processing Gateway (TPG) is accessible via secure HTTP endpoints. The base URL structure includes the Solana cluster and an API key for authentication.

```APIDOC
## POST /v1/{cluster}

### Description
This endpoint is used to process transactions on a specified Solana cluster using the Transaction Processing Gateway (TPG).

### Method
POST

### Endpoint
`https://tpg.sanctum.so/v1/{cluster}`

### Parameters
#### Path Parameters
- **cluster** (string) - Required - Specifies the Solana cluster targeted for transactions. Supported values: `mainnet`, `devnet`.

#### Query Parameters
- **apiKey** (string) - Required - The unique authentication key assigned to your project.

#### Request Body
- **method** (string) - Required - The method to be called (e.g., `buildGatewayTransaction`).
- **params** (array) - Required - An array of parameters for the specified method.

### Request Example
```json
{
  "method": "buildGatewayTransaction",
  "params": ["base64EncodedWireTransaction"]
}
```

### Response
#### Success Response (200)
- The structure of the success response depends on the method called.

#### Response Example
```json
{
  "result": "transaction_processing_result"
}
```
```
Tokens:
Raw