API Reference

import ZeroSettleEscrow

let escrow = ZeroSettleEscrow.shared

public weak var delegate: ZeroSettleEscrowDelegate?

public func configure(_ config: EscrowConfig)

ZeroSettleEscrow.shared.configure(EscrowConfig(
    privyAppId: "clxxxxxxxxxxxxxxxx",
    privyClientId: "client-xxxxxxxx",
    partnerAppId: 123,
    environment: .production
))

public func setGameAdminBackend(_ backend: GameAdminBackend)

let backend = MyGameAdminBackend(baseURL: URL(string: "https://api.mygame.com")!)
ZeroSettleEscrow.shared.setGameAdminBackend(backend)

public func initializeAuth() async

.task {
    await ZeroSettleEscrow.shared.initializeAuth()
}

public func sendOTP(to phoneNumber: String) async throws

public func verifyOTP(code: String, phoneNumber: String) async throws

public func logout() async

@Published public private(set) var balanceCents: Int

public func forceRefreshBalance() async

#if DEBUG
public func addDevFunds(cents: Int)
#endif

@discardableResult
public func startSession(
    gameDefinitionId: UUID,
    mode: GameMode = .singlePlayer,
    entryFeeCents: Int,
    maxPayoutMultiplier: Double
) async throws -> GameSession

public func confirmEscrow(sessionId: UUID) async throws

@discardableResult
public func submitResult(
    sessionId: UUID,
    playerResults: [PlayerResult]
) async throws

public func clearActiveSession()

public func getGameDefinition(name: String) async throws -> GameDefinition

public struct EscrowConfig: Sendable {
    let privyAppId: String
    let privyClientId: String
    let partnerAppId: Int
    let environment: NetworkEnvironment
    let blockchainEnvironment: NetworkEnvironment
    let localTokenMint: SolanaAddress?
    let gameBackendURL: URL?
}

public enum NetworkEnvironment: String {
    case production
    case development
    case local
}

public enum GameMode: String, Sendable, Codable {
    case singlePlayer = "single_player"
    case duel = "duel"
    case tournament = "tournament"
}

public struct GameSession: Identifiable, Sendable, Equatable, Codable {
    let id: UUID
    let gameDefinitionId: UUID
    let mode: GameMode
    let entryFeeCents: Int
    let maxPayoutMultiplier: Double
    let players: [SessionPlayer]
    let state: SessionState
    let createdAt: Date

    // Computed
    var totalPotCents: Int
    var stakedPlayerCount: Int
    var allPlayersStaked: Bool
}

public enum SessionState: String, Sendable, Codable {
    case waitingForPlayers = "waiting_for_players"
    case pendingStakes = "pending_stakes"
    case escrowConfirmed = "escrow_confirmed"
    case inProgress = "in_progress"
    case pendingSettlement = "pending_settlement"
    case settled = "settled"
    case cancelled = "cancelled"
}

public struct SessionPlayer: Sendable, Equatable, Identifiable, Codable {
    let id: UUID
    let wallet: SolanaAddress
    let stakeStatus: StakeStatus
}

public enum StakeStatus: String, Sendable, Codable {
    case pending = "pending"
    case staked = "staked"
    case refunded = "refunded"
}

public struct PlayerResult: Sendable, Codable {
    let userId: UUID
    let finalMultiplier: Double

    var multiplierBps: Int  // 2.5x = 250
}

public struct SettlementResult: Sendable, Codable {
    let sessionId: UUID
    let transactionSignature: String
    let payouts: [PlayerPayout]
    let platformFeeCents: Int
}

public struct PlayerPayout: Sendable, Codable {
    let userId: UUID
    let wallet: SolanaAddress
    let amountCents: Int
}

public struct GameDefinition: Sendable, Codable, Identifiable {
    let id: UUID
    let name: String
    let displayName: String
    let description: String?
    let payoutTable: PayoutTable
}

public enum PayoutTable: Sendable, Codable {
    case discrete(DiscretePayoutTable)
    case continuous(ContinuousPayoutTable)

    var maxMultiplier: Double
    func multiplier(for value: Double) -> Double
}

public struct SolanaAddress: Sendable, Equatable, Codable, Hashable {
    let base58: String

    init(_ base58String: String) throws  // Validates format
    init(trusted base58String: String)   // Skips validation
}

public enum ZeroSettleEscrowError: Error, LocalizedError {
    case notConfigured
    case notAuthenticated
    case noActiveSession
    case sessionNotReady(currentState: SessionState)
    case insufficientBalance(required: Int, available: Int)
    case invalidConfiguration(String)
    case signingFailed(String)
}

@MainActor
public protocol ZeroSettleEscrowDelegate: AnyObject {
    // Authentication
    func zeroSettleEscrowDidAuthenticate(userId: UUID, walletAddress: SolanaAddress)
    func zeroSettleEscrowDidLogout()
    func zeroSettleEscrowAuthenticationFailed(operation: String, error: Error)

    // Balance
    func zeroSettleEscrowDidUpdateBalance(_ balanceCents: Int)
    func zeroSettleEscrowBalanceFetchFailed(error: Error)

    // Sessions
    func zeroSettleEscrowDidCreateSession(_ session: GameSession)
    func zeroSettleEscrowSessionStateChanged(_ session: GameSession, from previousState: SessionState)
    func zeroSettleEscrowDidConfirm(session: GameSession)
    func zeroSettleEscrowDidSettleSession(_ result: SettlementResult)

    // Errors
    func zeroSettleEscrowSessionCreationFailed(request: SessionCreationRequest, error: Error, canRetry: Bool)
    func zeroSettleEscrowConfirmationFailed(sessionId: UUID, error: Error, canRetry: Bool)
    func zeroSettleEscrowSettlementFailed(sessionId: UUID, error: Error, canRetry: Bool)
}

public struct SessionCreationRequest: Sendable {
    let gameDefinitionId: UUID
    let mode: GameMode
    let entryFeeCents: Int
    let maxPayoutMultiplier: Double
}

public protocol GameAdminBackend: AnyObject, Sendable {
    /// Called when player has staked. Your server should stake the house side.
    func onPlayerStaked(
        sessionId: UUID,
        gameDefinitionId: Int,
        entryFeeLamports: Int,
        maxPayoutMultiplier: Double,
        playerWalletAddress: String
    ) async throws -> String  // Returns transaction signature

    /// Called when game ends. Your server should submit result on-chain.
    func submitResult(
        sessionId: UUID,
        finalMultiplierBps: Int,
        playerWalletAddress: String
    ) async throws
}