Frankfurt · Customer integration guide

Solana transaction landing

Retsina Fast Landing Service takes your signed Solana transactions over UDP and forwards each one, with stake-weighted quality of service (SWQoS) over staked QUIC connections that are already open, to the current leader and the next two leaders.

SWQoS is the point of the service. Leaders give priority to traffic that arrives on staked connections. Your transactions travel on ours, so they reach the leader with stake-weighted priority instead of competing with unstaked traffic.

From searcher to relayer it is UDP only: you send a datagram; there is no handshake, no session and no reply. The relayer is engineered for extremely high performance, and a transaction that fits in a single UDP packet takes an XDP fast path that bypasses the kernel network stack.

In short:

  1. Sign in to the customer portal with Google and set your sender IPv4 address (after NAT). It is whitelisted at 5 TPS by default within about a minute. Contact @RetsinaSoftware on Telegram for higher TPS.
  2. Build and sign your transaction as usual, and add a tip transfer to it.
  3. Send the raw serialized bytes in a UDP datagram to the relayer (several datagrams with a small header if the transaction is larger than 1232 bytes).
  4. Confirm landing on your own RPC. In our tests a transaction landed in the slot after the one in which the relayer received it.

Get access

The service is located in Frankfurt. Sign in to the customer portal with Google and set the public IPv4 address your packets leave from, after NAT. Your sender IP is whitelisted automatically at 5 TPS by default within about a minute.

Contact @RetsinaSoftware on Telegram for higher TPS. Send to frankfurt-landing.retsinasoftware.com, UDP port 9100; the portal shows the same address. Message Retsina Software on Telegram for your burst and minimum tip.

Pricing is pay per transaction: include a tip in each transaction. The default minimum is 100,000 lamports (0.0001 SOL) per transaction, paid only if the transaction lands and succeeds. Retsina Software tells you your minimum.

What you get from Retsina Software

The relayer address is the real service endpoint. The source IP and the limits below are examples; Retsina Software supplies your limits. The default limit is 5 TPS; the table shows a raised limit.

ItemExampleNotes
Relayer addressfrankfurt-landing.retsinasoftware.com:9100UDP over IPv4, port 9100. Resolve the name once and keep the socket connected.
Your whitelisted source IPs198.51.100.7IPv4. Datagrams from any other IP are dropped silently. Sign in to the customer portal with Google and set your public sender IP (after NAT); it is whitelisted at 5 TPS by default within about a minute. One sender IP per account. Contact @RetsinaSoftware on Telegram for higher TPS. Each IP has its own limit.
Your TPS limit200Transactions per second, per source IP
Your burst20How many transactions may arrive back to back; default is TPS / 10
Your minimum tip100000 lamportsPer transaction. See Tips

Retsina Software can change your limits and your minimum tip at any time without interrupting the service; nothing changes on your side.

What to send

The serialized, signed transaction: the same bytes you would base64-encode for the RPC sendTransaction call, sent raw (not base64, not base58). Legacy, v0 and v1 transactions are accepted.

Transaction sizeHow to send it
up to 1232 bytes (legacy, v0, small v1)one datagram, the transaction and nothing else
1233 to 4096 bytes (v1)several datagrams, each a 20-byte header plus a piece of the transaction

A transaction of 1232 bytes or less may also be sent as a single fragment (frag_cnt = 1), but there is no reason to.

Fragment header

20 bytes in front of each piece. Multi-byte integers are little-endian.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   0xF5        |   'R' 0x52    |   'T' 0x54    |   'X' 0x58    |  magic (4)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  version = 1  |   frag_idx    |   frag_cnt    |  flags = 0    |  1 + 1 + 1 + 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                         msg_id (8)                            +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         total_len (2)         |        frag_offset (2)        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
/                  payload (rest of the datagram)               /
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Byte offsetLengthFieldValue
04magicF5 52 54 58
41version1
51frag_idxindex of this fragment, starting at 0
61frag_cntnumber of fragments in this transaction, 1 to 16
71flags0
88msg_idany number; the same in every fragment of one transaction
162total_lenlength of the whole transaction, 1 to 4096
182frag_offsetposition of this fragment's first byte in the transaction
20…payloadthis fragment's bytes

Rules:

  • Keep every datagram at 1232 bytes or less (header included), so each fragment carries up to 1212 bytes. A 4096-byte transaction is 4 fragments.
  • The fragments must cover the transaction exactly: no gap, no overlap, and frag_offset + payload length ≤ total_len.
  • Send all fragments of a transaction from the same socket. They are matched by source IP, source port and msg_id.
  • msg_id must differ between transactions you have in flight at the same time from one socket. A counter is enough.
  • Order does not matter, but all fragments must arrive within 50 ms of the first one. Send them back to back.
  • Use full-size pieces (1212 bytes), as the code below does: at most 4 fragments per transaction. Fragments after the first have their own limit of 4 times your TPS, so a transaction cut into more, smaller pieces cannot be sent at your full rate.
  • If one fragment is lost, the transaction is lost: resend all of them with a new msg_id.

A v1 transaction is serialized with the message first and the signatures at the end; your SDK's serializer already does this. The network also requires a v1 transaction to state its resource limits (compute units and loaded account data size) in the transaction itself; without them it is rejected on chain, not by the relayer.

Tips

Every transaction you send must pay a tip, or it is dropped without being forwarded. The default minimum is 100,000 lamports (0.0001 SOL) per transaction; Retsina Software tells you yours.

The tip accounts:

RSTJbRASSqbY4kPS67KDRdtEZnhQYwvtkSXYHczzjwo
RSTNgqg11aKY9v6eLyzSjCK54B6QiRedU4aU8LaMetA
RSTSNRg344wYUFs3TDVPRDC22Rmuj6DqRu4SPAepYmZ
RSTXj28TQUDTATSsnXcXsWMdp7Bk3ZHB93zobMy9TX7
RSTnzSJeynWMtTe3KAsdGH6Yu5J27cPhP3qY873uW45

The rule:

  • Add a System Program transfer (the plain Transfer instruction, SOL) of at least your minimum tip to any one of the tip accounts. If the transaction has several such transfers, they are added up.
  • The transfer must be an instruction of the transaction itself (top level), not something a program does internally (a CPI).
  • The tip account must be in the transaction's own account list. In a v0 transaction, do not put the tip account in an address lookup table.
  • It can be anywhere among the instructions and paid from any signer of the transaction.

What does not count: TransferWithSeed, a transfer of wrapped SOL or any other token, a transfer made by your program, and a tip sent in a separate transaction.

What it costs you:

  • The tip is paid only if the transaction lands and succeeds, like any other instruction in it. A transaction that fails on chain pays the network fee and no tip.
  • The transfer uses 150 compute units and makes the tip account writable in your transaction. Count it in your compute unit limit.
  • The tip is separate from the priority fee. The priority fee goes to the leader and decides your place in the block; the tip pays for the relayer.

Spread your tips across the accounts (a different one per transaction) so your transactions do not all write-lock the same account.

// TypeScript (@solana/web3.js)
import { SystemProgram, PublicKey } from "@solana/web3.js";

const TIP_ACCOUNTS = [
  "RSTJbRASSqbY4kPS67KDRdtEZnhQYwvtkSXYHczzjwo",
  "RSTNgqg11aKY9v6eLyzSjCK54B6QiRedU4aU8LaMetA",
  "RSTSNRg344wYUFs3TDVPRDC22Rmuj6DqRu4SPAepYmZ",
  "RSTXj28TQUDTATSsnXcXsWMdp7Bk3ZHB93zobMy9TX7",
  "RSTnzSJeynWMtTe3KAsdGH6Yu5J27cPhP3qY873uW45",
].map((a) => new PublicKey(a));

transaction.add(
  SystemProgram.transfer({
    fromPubkey: payer.publicKey,
    toPubkey: TIP_ACCOUNTS[Math.floor(Math.random() * TIP_ACCOUNTS.length)],
    lamports: 100_000,
  }),
);
// Rust (solana-address, solana-system-interface)
use {solana_address::Address, solana_system_interface::instruction::transfer, std::str::FromStr};

const TIP_ACCOUNTS: [&str; 5] = [
    "RSTJbRASSqbY4kPS67KDRdtEZnhQYwvtkSXYHczzjwo",
    "RSTNgqg11aKY9v6eLyzSjCK54B6QiRedU4aU8LaMetA",
    "RSTSNRg344wYUFs3TDVPRDC22Rmuj6DqRu4SPAepYmZ",
    "RSTXj28TQUDTATSsnXcXsWMdp7Bk3ZHB93zobMy9TX7",
    "RSTnzSJeynWMtTe3KAsdGH6Yu5J27cPhP3qY873uW45",
];

// `n`: a counter you keep, so consecutive transactions use different accounts.
let tip_account = Address::from_str(TIP_ACCOUNTS[n % TIP_ACCOUNTS.len()]).unwrap();
instructions.push(transfer(&payer.pubkey(), &tip_account, 100_000));
# Python (solders)
import random
from solders.pubkey import Pubkey
from solders.system_program import TransferParams, transfer

TIP_ACCOUNTS = [Pubkey.from_string(a) for a in (
    "RSTJbRASSqbY4kPS67KDRdtEZnhQYwvtkSXYHczzjwo",
    "RSTNgqg11aKY9v6eLyzSjCK54B6QiRedU4aU8LaMetA",
    "RSTSNRg344wYUFs3TDVPRDC22Rmuj6DqRu4SPAepYmZ",
    "RSTXj28TQUDTATSsnXcXsWMdp7Bk3ZHB93zobMy9TX7",
    "RSTnzSJeynWMtTe3KAsdGH6Yu5J27cPhP3qY873uW45",
)]

instructions.append(transfer(TransferParams(
    from_pubkey=payer.pubkey(),
    to_pubkey=random.choice(TIP_ACCOUNTS),
    lamports=100_000,
)))

Limits and what happens to your transaction

CaseResult
Source IP not whitelisteddropped
Over your TPS limitdropped (not queued, not delayed)
Not shaped like a transaction, or larger than 4096 bytesdropped
The transaction tips less than your minimumdropped
Same transaction (same first signature) again within 1 second of the first time it was forwardeddropped as a duplicate
A fragment is lost, late, or inconsistent with the othersthe whole transaction is dropped after 50 ms
The relayer knows no leader at that moment (rare; for example just after it starts)dropped; a resend is not treated as a duplicate
Acceptedsent to the current leader and the next two, within tens of microseconds

What you need to know about these:

  • Rate limit. One transaction costs one token, whether it is one datagram or several. Tokens refill evenly at your TPS, up to your burst. Sending faster than that only loses transactions, so pace your sends.
  • Dropped transactions still cost a token, including duplicates, malformed ones and ones without the required tip.
  • No signature check, no simulation. The relayer does not verify signatures or run preflight. A transaction with a bad signature, an expired blockhash or a failing instruction is forwarded and then rejected by the leader. Simulate on your own RPC first if you need to.
  • No retry. Each transaction is sent once to each of the three leaders. If a leader is too busy to take it within about 400 ms, the copy for that leader is dropped.
  • Three leaders, one transaction. The same transaction reaches up to three leaders; only one of them can include it, exactly as when you send to several RPC nodes.
  • No feedback. You get no acknowledgement and no error. Confirm landing yourself with getSignatureStatuses or a signature subscription on your own RPC.
  • Resending. If a transaction has not landed, resend the same bytes no sooner than 1 second after it was first sent (earlier resends are dropped as duplicates), until its blockhash expires. Use a new msg_id each time for a multi-packet transaction. A resend costs a token like any other send; it does not cost a second tip, because the transaction can only land once.
  • Fees still matter. The relayer gets your transaction to the leader quickly; the leader still orders by priority fee.

Code

The examples send to the service endpoint, frankfurt-landing.retsinasoftware.com:9100.

Each snippet has one function, send_tx, that picks the right form.

Rust (standard library only)

use std::net::UdpSocket;

const MAX_BARE_TX: usize = 1232; // largest tx sent as one plain datagram
const MAX_TX: usize = 4096;      // largest tx accepted
const MAX_DATAGRAM: usize = 1232;
const HEADER_LEN: usize = 20;

/// Send one serialized, signed transaction. `sock` must be connected to the
/// relayer. `msg_id` is only used for a multi-packet transaction.
fn send_tx(sock: &UdpSocket, tx: &[u8], msg_id: u64) -> std::io::Result<()> {
    assert!(!tx.is_empty() && tx.len() <= MAX_TX);

    // Single packet: the datagram is the transaction.
    if tx.len() <= MAX_BARE_TX {
        sock.send(tx)?;
        return Ok(());
    }

    // Multi packet: 20-byte header + piece, for each piece.
    let chunk = MAX_DATAGRAM - HEADER_LEN;
    let cnt = tx.len().div_ceil(chunk);
    for (idx, part) in tx.chunks(chunk).enumerate() {
        let mut d = Vec::with_capacity(HEADER_LEN + part.len());
        d.extend_from_slice(&[0xF5, b'R', b'T', b'X']);              // magic
        d.extend_from_slice(&[1, idx as u8, cnt as u8, 0]);          // version, frag_idx, frag_cnt, flags
        d.extend_from_slice(&msg_id.to_le_bytes());                  // msg_id
        d.extend_from_slice(&(tx.len() as u16).to_le_bytes());       // total_len
        d.extend_from_slice(&((idx * chunk) as u16).to_le_bytes());  // frag_offset
        d.extend_from_slice(part);
        sock.send(&d)?;
    }
    Ok(())
}

fn main() -> std::io::Result<()> {
    let sock = UdpSocket::bind("0.0.0.0:0")?;
    sock.connect("frankfurt-landing.retsinasoftware.com:9100")?;

    let small_tx: Vec<u8> = std::fs::read("small-tx.bin")?; // e.g. 400 bytes
    let large_tx: Vec<u8> = std::fs::read("large-tx.bin")?; // e.g. 3000 bytes, v1

    let mut msg_id: u64 = 0;
    for tx in [&small_tx, &large_tx] {
        msg_id += 1;
        send_tx(&sock, tx, msg_id)?; // 1 datagram for small_tx, 3 for large_tx
    }
    Ok(())
}

Python

import socket
import struct

MAX_BARE_TX = 1232
MAX_TX = 4096
MAX_DATAGRAM = 1232
HEADER_LEN = 20


def send_tx(sock: socket.socket, tx: bytes, msg_id: int) -> None:
    """Send one serialized, signed transaction on a connected UDP socket."""
    assert 0 < len(tx) <= MAX_TX

    # Single packet: the datagram is the transaction.
    if len(tx) <= MAX_BARE_TX:
        sock.send(tx)
        return

    # Multi packet: 20-byte header + piece, for each piece.
    chunk = MAX_DATAGRAM - HEADER_LEN
    cnt = -(-len(tx) // chunk)
    for idx in range(cnt):
        offset = idx * chunk
        header = struct.pack(
            "<4sBBBBQHH",          # little-endian, 20 bytes
            b"\xf5RTX",            # magic
            1,                     # version
            idx,                   # frag_idx
            cnt,                   # frag_cnt
            0,                     # flags
            msg_id,                # msg_id
            len(tx),               # total_len
            offset,                # frag_offset
        )
        sock.send(header + tx[offset:offset + chunk])


sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.connect(("frankfurt-landing.retsinasoftware.com", 9100))

small_tx = open("small-tx.bin", "rb").read()
large_tx = open("large-tx.bin", "rb").read()

send_tx(sock, small_tx, msg_id=1)   # 1 datagram
send_tx(sock, large_tx, msg_id=2)   # 3 datagrams for a 3000-byte tx

TypeScript (Node.js)

import dgram from "node:dgram";

const MAX_BARE_TX = 1232;
const MAX_TX = 4096;
const MAX_DATAGRAM = 1232;
const HEADER_LEN = 20;

/** Send one serialized, signed transaction on a connected UDP socket. */
function sendTx(sock: dgram.Socket, tx: Uint8Array, msgId: bigint): void {
  if (tx.length === 0 || tx.length > MAX_TX) throw new Error("bad tx length");

  // Single packet: the datagram is the transaction.
  if (tx.length <= MAX_BARE_TX) {
    sock.send(tx);
    return;
  }

  // Multi packet: 20-byte header + piece, for each piece.
  const chunk = MAX_DATAGRAM - HEADER_LEN;
  const cnt = Math.ceil(tx.length / chunk);
  for (let idx = 0; idx < cnt; idx++) {
    const offset = idx * chunk;
    const part = tx.subarray(offset, offset + chunk);
    const d = Buffer.alloc(HEADER_LEN + part.length);
    d.set([0xf5, 0x52, 0x54, 0x58], 0); // magic
    d.writeUInt8(1, 4);                 // version
    d.writeUInt8(idx, 5);               // frag_idx
    d.writeUInt8(cnt, 6);               // frag_cnt
    d.writeUInt8(0, 7);                 // flags
    d.writeBigUInt64LE(msgId, 8);       // msg_id
    d.writeUInt16LE(tx.length, 16);     // total_len
    d.writeUInt16LE(offset, 18);        // frag_offset
    d.set(part, HEADER_LEN);
    sock.send(d);
  }
}

const sock = dgram.createSocket("udp4");
sock.connect(9100, "frankfurt-landing.retsinasoftware.com", () => {
  // With @solana/web3.js: const tx = transaction.serialize();
  const smallTx: Uint8Array = /* serialized signed tx, <= 1232 bytes */ new Uint8Array();
  const largeTx: Uint8Array = /* serialized signed v1 tx, <= 4096 bytes */ new Uint8Array();
  sendTx(sock, smallTx, 1n); // 1 datagram
  sendTx(sock, largeTx, 2n); // several datagrams
});

Practical advice

  • Reuse one socket. Open it once, connect it to the relayer, and keep it. There is nothing to warm up on your side.
  • Do not let the network fragment your datagrams. Stay at 1232 bytes or less per datagram.
  • Pace, do not burst. At 200 TPS with burst 20, 20 transactions may go at once; after that one is accepted every 5 ms.
  • Send from the whitelisted IP. Check the address your packets actually leave from if you are behind NAT or have several interfaces.
  • Be close. UDP delivery time to the relayer is the largest part of your latency; the relayer itself adds tens of microseconds.
  • Use a fresh blockhash and set a priority fee. The relayer does not change your transaction; what the leader does with it is decided by what is in it.

Troubleshooting

Since there is no reply, a transaction that does not land looks the same for every cause. Check in this order:

  1. Is the source IP the one that was whitelisted?
  2. Are you under your TPS limit, counting resends, duplicates and malformed sends?
  3. Are the bytes the raw serialized transaction (not base64 or base58)?
  4. For a multi-packet transaction: same socket for all fragments, frag_cnt and total_len the same in every fragment, integers little-endian, all sent within 50 ms?
  5. Is there a top-level System transfer of at least your minimum to one of the tip accounts, with the tip account in the transaction's own account list (not a lookup table)?
  6. Does the transaction pass simulateTransaction on your RPC, with a recent blockhash? If it landed but failed, getSignatureStatuses shows the error.

Retsina Software keeps a log of every transaction received from your IP that passed the rate limit: time, first signature, size, number of datagrams, and what happened to it (forwarded and to which leaders in which slot, duplicate, malformed and why, or tip too small and how much it offered). Give Retsina Software the signature and the time, and we can tell you which case it was. Transactions dropped by the rate limit are only counted, not logged.