Setup Guide

This is how you join TIN. Onboarding registers your block engine on-chain so that every opted-in Rakurai validator connects to it automatically, and your orderflow starts competing for inclusion alongside the other landing services.

You handover the Rakurai team two things — a discovery endpoint that lists your block engine URLs, and a wallet pubkey you control for PSA / MCA settlement — and Rakurai performs the on-chain registration.This page covers that handover, the gRPC services your server must expose and the role each one needs.

Audience: Block engines, searchers, and partners integrating transaction landing with Rakurai.

On Discord or Telegram, share:

Your block-engine discovery / global URL, and your P2C URL (if different)
A wallet pubkey you control (you hold the private key) — used for PSA / MCA recording and settlement

Rakurai registers endpoints and creates per-validator PSA / MCA (and tip / TCA wiring as needed). Keep that key secure for epoch settlement (rakurai-revshare).

2. Bundle support / global block-engine endpoint

Rakurai supports multiple block engines — transaction landing services can send bundles directly to Rakurai nodes. Share an endpoint with the Rakurai team that returns a list of block engine addresses run by your service. Rakurai validators automatically connect to the lowest-latency endpoint (just like Jito's).

Example URL: https://mainnet.block-engine.jito.wtf

2.1. Endpoint: GetBlockEngineEndpoints

Response:

global_endpoint {
  block_engine_url: "https://gateway.your-provider.com"
  shredstream_receiver_address: ""
}
regioned_endpoints {
  block_engine_url: "https://fra.gateway.your-provider.com"
  shredstream_receiver_address: ""
}

See your gRPC proto definition for the full request/response schema.

2.2. Minimum requirements

If you only operate one endpoint, returning just global_endpoint is fine. global_endpoint.block_engine_url must be a valid, reachable block engine URL.

Rakurai will add this URL to an on-chain PDA so that all Rakurai nodes that have opted in for this feature can connect seamlessly.

Once the block engine is connected, you can send bundles directly. Each bundle must include a tip transfer instruction to one of Rakurai's tip accounts.

Recommended tip

1,000,000 lamports (0.001 SOL) per tipped transaction or bundle (in addition to normal priority fees). Tip accounts and virtual priority: Tips. Custom tip accounts: Tips — custom accounts.

3. Required gRPC services

The connection is outbound from the validator

The validator connects to your block_engine_url. You run a gRPC server; the validator does not open a listen port for you. Bind the server so validators can reach it (public IP or resolvable hostname). http:// and https:// are both accepted.

Protos: auth.proto, block_engine.proto, packet.proto.

Path	What you provide	What the validator does
Block engine (bundles)	A global / discovery endpoint (`GetBlockEngineEndpoints`) that returns your `block_engine_url`(s)	Connects automatically to the lowest-latency endpoint
P2C (post-pack)	The URL your Relayer gRPC server listens on	Connects directly to that URL for `StartExpiringPacketStream`

Path	Role	Services
Bundles	`VALIDATOR`	`auth.AuthService` + `block_engine.BlockEngineValidator` (`SubscribePackets` / `SubscribeBundles`)
P2C	`RELAYER`	`auth.AuthService` + `block_engine.BlockEngineRelayer` (`StartExpiringPacketStream`)

Bundles — your server → validator (BlockEngineValidator):

auth.AuthService with role VALIDATOR
block_engine.BlockEngineValidator — SubscribePackets / SubscribeBundles

Post-pack (P2C) — validator → your server (BlockEngineRelayer). Full Relayer setup, packets, and reply bundles: Using P2C.

auth.AuthService with role RELAYER
block_engine.BlockEngineRelayer — StartExpiringPacketStream

3.1. Same URL for bundles and P2C

If you register one URL for both block-engine (bundles) and post-pack (P2C), that server must expose all three services:

Service	What the validator uses
`auth.AuthService`	Roles `VALIDATOR` (bundles) and `RELAYER` (P2C)
`block_engine.BlockEngineValidator`	`SubscribePackets` / `SubscribeBundles`
`block_engine.BlockEngineRelayer`	`StartExpiringPacketStream`

Same URL without the Relayer role

If only the Validator role/API is implemented, bundles can work and P2C will still fail. Validator log: SchedulerUpdateNotifier: connection to {url} failed.

You may use separate URLs instead: the block-engine URL only needs Validator + BlockEngineValidator; the P2C URL only needs Relayer + BlockEngineRelayer.

4. For validators — block-engine Admin RPC

Validator operators can see which block engines are connected and, if they choose, block any of them through Admin RPC.

Admin IPC is request/response: keep the socket open briefly so socat can read the reply before stdin closes.

4.1. getBlockEngineUrls

Returns the list of block engine URLs maintained by the scheduler.

(echo '{"jsonrpc":"2.0","id":1,"method":"getBlockEngineUrls","params":[]}'; sleep 1) \
  | socat - UNIX-CONNECT:admin.rpc | jq

Example response:

{
    "active_secondary_entries": [],
    "admin_secondary_entries": [],
    "blocklisted_uuids": [],
    "onchain_secondary_entries": [],
    "primary_url": "https://frankfurt.mainnet.block-engine.jito.wtf"
}

4.2. setBlockEngineUrlBlocklist

Sets the blocklist to disconnect block engine URLs by UUID. Each call replaces the entire blocklist. Pass an empty array to clear it.

Add "<BlockEngine1>" UUID to blocklist:

(echo '{"jsonrpc":"2.0","id":1,"method":"setBlockEngineUrlBlocklist","params":[["<BlockEngine1>"]]}'; sleep 1) \
  | socat - UNIX-CONNECT:admin.rpc

Clear blocklist:

(echo '{"jsonrpc":"2.0","id":1,"method":"setBlockEngineUrlBlocklist","params":[[]]}'; sleep 1) \
  | socat - UNIX-CONNECT:admin.rpc

Clearing the blocklist

setBlockEngineUrlBlocklist takes one parameter: an array of UUIDs. To clear the blocklist you must pass an empty array inside the parameter list — params:[[]]. Writing params:[] omits the parameter entirely and the blocklist is not cleared.

Post-pack endpoint Admin RPC: Using P2C — Commands.

Tips — tip accounts, virtual priority, TCA (not PSA/MCA)
Post-pack confirmations — stream access (PSA) and backrun share (MCA)
Using P2C — Relayer gRPC, packets, reply bundles