Address Derivation

The SDK provides helper functions to derive Program Derived Addresses (PDAs) for all TIX Protocol accounts.

Overview

All TIX Protocol state is stored in PDAs, which are deterministic addresses derived from seeds. The SDK provides functions to compute these addresses locally.

Protocol Config PDA

The protocol configuration account.

import { protocolConfigPda } from "@tixprotocol/sdk";

const [pda, bump] = protocolConfigPda();
console.log(`Protocol Config: ${pda.toBase58()}`);

Seeds: [b"protocol_config"]

Integrator PDA

Integrator account for a marketplace/venue.

import { integratorPda } from "@tixprotocol/sdk";

const integratorIdentity = new PublicKey("...");
const [pda, bump] = integratorPda(integratorIdentity);
console.log(`Integrator: ${pda.toBase58()}`);

Seeds: [b"integrator", integrator_identity]

Event PDA

Event account containing supply and royalty configuration.

import { eventPda } from "@tixprotocol/sdk";

const eventId = 1001n;
const [pda, bump] = eventPda(eventId);
console.log(`Event: ${pda.toBase58()}`);

Seeds: [b"event", event_id (u64 LE)]

Permit Page PDA

Storage page for permits (128 per page).

import { permitPagePda, eventPda } from "@tixprotocol/sdk";

const eventId = 1001n;
const [eventPubkey] = eventPda(eventId);
const pageIdx = 0n; // First page (tickets 0-127)

const [pda, bump] = permitPagePda(eventPubkey, pageIdx);
console.log(`Permit Page 0: ${pda.toBase58()}`);

Seeds: [b"permit_page", event_pubkey, page_idx (u64 LE)]

Page Calculation Helper

const PERMITS_PER_PAGE = 128n;

function getPageForTicket(ticketId: bigint): bigint {
  return ticketId / PERMITS_PER_PAGE;
}

function getLocalIndex(ticketId: bigint): number {
  return Number(ticketId % PERMITS_PER_PAGE);
}

// Example: Ticket ID 300
const ticketId = 300n;
const pageIdx = getPageForTicket(ticketId); // 2n
const localIdx = getLocalIndex(ticketId); // 44

const [eventPubkey] = eventPda(1001n);
const [pagePda] = permitPagePda(eventPubkey, pageIdx);

Listing PDA

Secondary market listing account.

import { listingPda } from "@tixprotocol/sdk";

const eventId = 1001n;
const ticketId = 42n;

const [pda, bump] = listingPda(eventId, ticketId);
console.log(`Listing: ${pda.toBase58()}`);

Seeds: [b"listing", event_id (u64 LE), ticket_id (u64 LE)]

Associated Token Account (ATA)

For USDC treasury and payout accounts, use SPL Token helpers:

import { getAssociatedTokenAddress } from "@solana/spl-token";

// Integrator treasury ATA
const [integratorPubkey] = integratorPda(integratorIdentity);
const treasuryAta = await getAssociatedTokenAddress(
  USDC_MINT,
  integratorPubkey,
  true // allowOwnerOffCurve for PDA
);

// User's USDC ATA
const userUsdcAta = await getAssociatedTokenAddress(USDC_MINT, userWallet);

Complete Example

import { PublicKey } from "@solana/web3.js";
import { getAssociatedTokenAddress } from "@solana/spl-token";
import {
  protocolConfigPda,
  integratorPda,
  eventPda,
  permitPagePda,
  listingPda,
} from "@tixprotocol/sdk";

async function deriveAllAddresses(
  integratorIdentity: PublicKey,
  eventId: bigint,
  ticketId: bigint,
  usdcMint: PublicKey
) {
  // Protocol config
  const [protocolConfig] = protocolConfigPda();

  // Integrator and treasury
  const [integrator] = integratorPda(integratorIdentity);
  const treasury = await getAssociatedTokenAddress(usdcMint, integrator, true);

  // Event
  const [event] = eventPda(eventId);

  // Permit page for ticket
  const pageIdx = ticketId / 128n;
  const [permitPage] = permitPagePda(event, pageIdx);

  // Listing (if exists)
  const [listing] = listingPda(eventId, ticketId);

  return {
    protocolConfig,
    integrator,
    treasury,
    event,
    permitPage,
    listing,
  };
}

// Usage
const addresses = await deriveAllAddresses(
  integratorIdentity,
  1001n,
  42n,
  USDC_MINT
);

console.log("Protocol Config:", addresses.protocolConfig.toBase58());
console.log("Integrator:", addresses.integrator.toBase58());
console.log("Treasury:", addresses.treasury.toBase58());
console.log("Event:", addresses.event.toBase58());
console.log("Permit Page:", addresses.permitPage.toBase58());
console.log("Listing:", addresses.listing.toBase58());

Low-Level Derivation

If you need to derive PDAs manually:

import { PublicKey } from "@solana/web3.js";
import { PROGRAM_ID } from "@tixprotocol/sdk";

// Protocol config
const [protocolConfig] = PublicKey.findProgramAddressSync(
  [Buffer.from("protocol_config")],
  PROGRAM_ID
);

// Integrator
const [integrator] = PublicKey.findProgramAddressSync(
  [Buffer.from("integrator"), integratorIdentity.toBuffer()],
  PROGRAM_ID
);

// Event
const eventIdBuffer = Buffer.alloc(8);
eventIdBuffer.writeBigUInt64LE(eventId);
const [event] = PublicKey.findProgramAddressSync(
  [Buffer.from("event"), eventIdBuffer],
  PROGRAM_ID
);

// Permit page
const pageIdxBuffer = Buffer.alloc(8);
pageIdxBuffer.writeBigUInt64LE(pageIdx);
const [permitPage] = PublicKey.findProgramAddressSync(
  [Buffer.from("permit_page"), event.toBuffer(), pageIdxBuffer],
  PROGRAM_ID
);

// Listing
const ticketIdBuffer = Buffer.alloc(8);
ticketIdBuffer.writeBigUInt64LE(ticketId);
const [listing] = PublicKey.findProgramAddressSync(
  [Buffer.from("listing"), eventIdBuffer, ticketIdBuffer],
  PROGRAM_ID
);

Seed Reference

Account	Seeds
ProtocolConfig	[b"protocol_config"]
Integrator	[b"integrator", identity_pubkey]
Event	[b"event", event_id_le_bytes]
PermitPage	[b"permit_page", event_pubkey, page_idx_le_bytes]
Listing	[b"listing", event_id_le_bytes, ticket_id_le_bytes]