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:
- 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.
- Build and sign your transaction as usual, and add a tip transfer to it.
- 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).
- 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.
| Item | Example | Notes |
|---|---|---|
| Relayer address | frankfurt-landing.retsinasoftware.com:9100 | UDP over IPv4, port 9100. Resolve the name once and keep the socket connected. |
| Your whitelisted source IPs | 198.51.100.7 | IPv4. 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 limit | 200 | Transactions per second, per source IP |
| Your burst | 20 | How many transactions may arrive back to back; default is TPS / 10 |
| Your minimum tip | 100000 lamports | Per 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 size | How 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 offset | Length | Field | Value |
|---|---|---|---|
| 0 | 4 | magic | F5 52 54 58 |
| 4 | 1 | version | 1 |
| 5 | 1 | frag_idx | index of this fragment, starting at 0 |
| 6 | 1 | frag_cnt | number of fragments in this transaction, 1 to 16 |
| 7 | 1 | flags | 0 |
| 8 | 8 | msg_id | any number; the same in every fragment of one transaction |
| 16 | 2 | total_len | length of the whole transaction, 1 to 4096 |
| 18 | 2 | frag_offset | position of this fragment's first byte in the transaction |
| 20 | … | payload | this 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_idmust 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:
RSTJbRASSqbY4kPS67KDRdtEZnhQYwvtkSXYHczzjwoRSTNgqg11aKY9v6eLyzSjCK54B6QiRedU4aU8LaMetARSTSNRg344wYUFs3TDVPRDC22Rmuj6DqRu4SPAepYmZRSTXj28TQUDTATSsnXcXsWMdp7Bk3ZHB93zobMy9TX7RSTnzSJeynWMtTe3KAsdGH6Yu5J27cPhP3qY873uW45The rule:
- Add a System Program transfer (the plain
Transferinstruction, 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
| Case | Result |
|---|---|
| Source IP not whitelisted | dropped |
| Over your TPS limit | dropped (not queued, not delayed) |
| Not shaped like a transaction, or larger than 4096 bytes | dropped |
| The transaction tips less than your minimum | dropped |
| Same transaction (same first signature) again within 1 second of the first time it was forwarded | dropped as a duplicate |
| A fragment is lost, late, or inconsistent with the others | the 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 |
| Accepted | sent 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
getSignatureStatusesor 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_ideach 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,
connectit 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:
- Is the source IP the one that was whitelisted?
- Are you under your TPS limit, counting resends, duplicates and malformed sends?
- Are the bytes the raw serialized transaction (not base64 or base58)?
- For a multi-packet transaction: same socket for all fragments,
frag_cntandtotal_lenthe same in every fragment, integers little-endian, all sent within 50 ms? - 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)?
- Does the transaction pass
simulateTransactionon your RPC, with a recent blockhash? If it landed but failed,getSignatureStatusesshows 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.