Account Model

TIX Protocol uses Program Derived Addresses (PDAs) for all on-chain state. This ensures addresses are deterministic and can be computed by any client.

Account Overview

Account	PDA Seeds	Purpose
ProtocolConfig	[b"protocol_config"]	Global settings
Integrator	[b"integrator", integrator_identity]	Marketplace/operator account
Event	[b"event", event_id (u64 LE)]	Event configuration
PermitPage	[b"permit_page", event_pubkey, page_idx (u64 LE)]	Ticket storage (128 per page)
Listing	[b"listing", event_id (u64 LE), ticket_id (u64 LE)]	Secondary market listing

ProtocolConfig

The account that captures global settings and the protocol admin.

Seeds: [b"protocol_config"]

Field	Type	Description
usdc_mint	Pubkey	USDC token mint address
default_royalty_vault	Pubkey	ATA for protocol fees
authority	Pubkey	Protocol operator public key
usdc_decimals	u8	USDC mint decimals (usually 6)
permit_fee_minor	u64	Fee per ticket issuance
p2p_transfer_fee_minor	u64	Fee per direct transfer
resale_fee_bps	u16	Resale fee in basis points

Integrator

Represents a marketplace or operator that can create events and issue tickets.

Seeds: [b"integrator", integrator_identity]

Field	Type	Description
authority	Pubkey	Integrator's signing authority
status	IntegratorStatus	Active or Suspended
treasury_usdc	Pubkey	USDC treasury ATA (derived from PDA)

Integrator Status

enum IntegratorStatus {
    Active,    // Can operate normally
    Suspended, // Blocked from operations
}

Event

Stores event-scope configuration and minting counters.

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

Field	Type	Description
integrator	Pubkey	Owning integrator PDA
integrator_authority	Pubkey	Authority at creation time
royalty_bps	u16	Royalty percentage (basis points)
min_royalty_floor	u64	Minimum royalty in minor units
royalty_recipients	[RoyaltyRecipient; 3]	Up to 3 royalty recipients
total_supply	u64	Maximum tickets for event
minted	u64	Current issued count
sealed	bool	Reserved for future supply-locking

RoyaltyRecipient

struct RoyaltyRecipient {
    destination: Pubkey,  // USDC ATA to receive royalties
    bps: u16,             // Basis points share
}

Note: The sum of all recipient bps must equal the event's royalty_bps.

PermitPage

Each page holds up to 128 permits. Pages allocate once and then mutate.

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

Field	Type	Description
event	Pubkey	Parent event account
page_idx	u64	Page index
permits	Vec<Permit>	Array of permits (max 128)

Permit

struct Permit {
    owner: Pubkey,      // Current ticket holder
    status: u8,         // 0=Active, 1=Used, 2=Void
    version: u64,       // Increments on every change
    ticket_id: u64,     // Unique ticket identifier
    padding: [u8; 16],  // Listing lock data
}

Permit Status

Value	Status	Description
0	Active	Can be transferred or sold
1	Used	Redeemed at venue
2	Void	Cancelled/refunded

Listing Lock (Padding)

The padding bytes encode listing lock information:

Bytes	Purpose
padding[0]	Lock flag (1 = listing active)
padding[1..9]	Expiry timestamp (i64 little-endian)

Listing

Tracks secondary-market listings and enforces per-ticket locks.

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

Field	Type	Description
seller	Pubkey	Listing creator
ask_price_minor	u64	Price in USDC minor units
buyer_allow	Option<Pubkey>	Optional allowlisted buyer
payout_ata	Pubkey	Seller's payout destination
expires_at	i64	Listing expiration timestamp
listed_at	i64	Listing creation timestamp
permit_version	u64	Expected permit version
active	bool	Whether listing is active

PDA Derivation Examples

// 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
);