# From rust-sdk directory
make docs-rust

# iOS-specific docs
cargo doc --no-deps -p privacy-boost-ios

init(config: PrivacyBoostConfig) throws

var isConnected: Bool { get }
var isAuthenticated: Bool { get }

func authenticate(wallet: WalletDelegate, keySource: KeySource? = nil, tokenProvider: TokenProvider? = nil) async throws -> AuthResult

func submitCredential(_ credential: String, tokenProvider: TokenProvider? = nil) async throws -> LoginResult

func logout()

func clearSession()

func lock()

func getPrivacyAddress() -> String?
func getMpk() -> String?
func getWalletAddress() -> String?

func getBalance(tokenAddress: String) async throws -> TokenBalance

func getAllBalances() async throws -> [TokenBalance]

func getFees(tokenAddress: String) async throws -> FeeRates

func getGatewayFees(
    tokenAddress: String,
    gatewayAddress: String,
    gatewaySelector: String? = nil
) async throws -> FeeRates

func shield(tokenAddress: String, amount: String) async throws -> ShieldResult

func unshield(tokenAddress: String, amount: String, recipient: String) async throws -> UnshieldResult

func send(tokenAddress: String, amount: String, recipientPrivacyAddress: String) async throws -> TransferResult

func sendBatch(tokenAddress: String, recipients: [TransferRecipient]) async throws -> TransferResult

func prepareShield(tokenAddress: String, amount: String, recipient: String?) async throws -> PreparedShield

func earnDeposit(vaultAddress: String, amount: String, slippageBps: UInt32?) async throws -> EarnResult
func earnRedeem(vaultAddress: String, amount: String, slippageBps: UInt32?) async throws -> EarnResult

func listEarnVaults() async throws -> EarnVaultCatalog
func getEarnVault(vaultAddress: String) async throws -> EarnVaultDetail

let catalog = try await sdk.listEarnVaults()
for vault in catalog.vaults where vault.listed {
    let apy = vault.apy.net.map { String(format: "%.2f%%", $0 * 100) } ?? "n/a"
    let open = vault.availability.deposit.canSubmit
    print("\(vault.name) \(apy) deposits \(open ? "open" : "closed")")
}

func getGatewayConfig() async throws -> GatewayConfig

func getEarnVaultHistory(
    vaultAddress: String,
    metric: EarnHistoryMetric,
    period: EarnHistoryPeriod? = nil
) async throws -> EarnVaultHistory
func getEarnVaultCharts(vaultAddress: String, period: EarnHistoryPeriod? = nil) async throws -> EarnVaultCharts

func getTransactionHistory(
    txType: String?,
    tokenAddress: String?,
    limit: UInt32?
) async throws -> [Transaction]

func queryTransactionHistory(query: TransactionHistoryQuery) async throws -> TransactionsResult

// Incoming transactions for token id 1, 25 per page, gateway operations collapsed
let page = try await sdk.queryTransactionHistory(query: TransactionHistoryQuery(
    tokenId: 1,
    direction: .incoming,
    limit: 25,
    collapseGateway: true
))
for tx in page.data {
    print(tx.txHash)
}
// page.next is the cursor for the following page; nil at the end

func exportSession() -> ExportedSession?

func importSession(_ session: ExportedSession) throws -> Bool

func listContacts(limit: UInt32? = nil, cursor: String? = nil) async throws -> ContactPage

func createContact(input: CreateContactInput) async throws -> Contact

func bulkCreateContacts(contacts: [CreateContactInput]) async throws -> BulkContactsResult

func updateContact(id: String, input: UpdateContactInput) async throws -> Contact

func deleteContact(id: String) async throws

func listLabels(limit: UInt32? = nil, cursor: String? = nil) async throws -> TransactionLabelPage

func upsertLabel(txHash: String, input: UpsertLabelInput) async throws -> TransactionLabel

func deleteLabel(txHash: String) async throws

// Save a contact, then label a transfer to them.
let alice = try await sdk.createContact(input: CreateContactInput(
    privacyAddress: "0x04...alice",
    nickname: "Alice",
    ethAddress: "0x1234...abcd",
    metadata: ["team": "design"]
))

_ = try await sdk.upsertLabel(txHash: transfer.txHash, input: UpsertLabelInput(
    contactId: alice.id,
    memo: "Dinner split"
))

// Later: clear the ETH address and keep everything else.
_ = try await sdk.updateContact(id: alice.id, input: UpdateContactInput(
    ethAddress: .clear,
    nickname: .keep,
    emoji: .keep,
    metadata: .keep
))

// Page through contacts.
var cursor: String? = nil
repeat {
    let page = try await sdk.listContacts(limit: 50, cursor: cursor)
    for contact in page.contacts where !contact.decryptionFailed {
        print(contact.nickname, contact.privacyAddress ?? "")
    }
    cursor = page.nextCursor
} while cursor != nil

func getStartaleCampaignProgress() async throws -> StartaleCampaignProgress

let progress = try await sdk.getStartaleCampaignProgress()
if progress.hasDepositedAtLeast10Usd { missions.markComplete(.deposit) }
if progress.hasMadeTransfer { missions.markComplete(.transfer) }

func resolveIdentity(identifier: String) async throws -> IdentityResult

func createChainContext(config: ChainContextConfig) throws -> ChainContextHandle

func isValidPrivacyAddress(_ address: String) -> Bool
func isValidAddress(_ address: String) -> Bool
func parseAmount(_ amount: String, decimals: UInt8) throws -> String
func formatAmount(_ wei: String, decimals: UInt8) throws -> String

func chainId() -> UInt64
func isAuthenticated() -> Bool
func isRegistered() -> Bool
func authenticate(wallet: WalletDelegate, externalToken: String? = nil) async throws -> LoginResult
func clearSession()

// Transactions
func shield(tokenAddress: String, amount: String) async throws -> ShieldResult
func prepareShield(tokenAddress: String, amount: String, recipient: String?) async throws -> PreparedShield
func unshield(tokenAddress: String, amount: String, recipient: String) async throws -> UnshieldResult
func send(tokenAddress: String, amount: String, recipientPrivacyAddress: String) async throws -> TransferResult
func sendBatch(tokenAddress: String, recipients: [TransferRecipient]) async throws -> TransferResult
func unwrapWeth(amount: String, recipient: String) async throws -> String
func consolidateNotes(tokenAddress: String, maxRounds: UInt32) async throws -> ConsolidateResult

// Balances, tokens, and fees
func getBalance(tokenAddress: String) async throws -> TokenBalance
func getAllBalances() async throws -> [TokenBalance]
func getRegisteredTokens() async throws -> [RegisteredToken]
func getTokenByAddress(address: String) async throws -> RegisteredToken
func getFees(tokenAddress: String) async throws -> FeeRates
func getGatewayFees(tokenAddress: String, gatewayAddress: String, gatewaySelector: String? = nil) async throws -> FeeRates

// Status and history
func getShieldStatus(requestId: String) async throws -> ShieldStatus
func getTransferStatus(id: String) async throws -> TransactionStatus
func getUnshieldStatus(id: String) async throws -> TransactionStatus
func getTransactionHistory(txType: String?, limit: UInt32?, cursor: String?) async throws -> TransactionsResult
func getCollapsedTransactionHistory(txType: String?, limit: UInt32?, cursor: String?) async throws -> TransactionsResult
func queryTransactionHistory(query: TransactionHistoryQuery) async throws -> TransactionsResult
func getUnspentNotes(tokenAddress: String?) async throws -> [UnspentNote]

// Pending transactions
func addPendingTransaction(tx: PendingTransaction)
func getPendingTransactions() -> [PendingTransaction]
func getAllPendingTransactions() -> [PendingTransaction]
func refreshPendingTransactions() async throws -> UInt32
func refreshPendingTransactionsDetailed() async throws -> RefreshPendingSummary
func waitForPreconfirmation(requestId: String, timeoutMs: UInt64) async throws -> PendingTransaction
func waitForFinality(requestId: String, timeoutMs: UInt64) async throws -> PendingTransaction

func sdkVersion() -> String
func generateMnemonic() throws -> String
func registerKeychainDelegate(delegate: KeychainDelegate, service: String? = nil)
func hasKeychainDelegate() -> Bool

func buildShieldPayload(
    tokenAddress: String,
    amount: String,
    recipient: String,
    tokenId: UInt16,
    shieldContractAddress: String,
    wethContractAddress: String?,
    teePublicKey: String,
    minShieldAmount: String?,
    emitApprove: Bool
) throws -> PreparedShield

func finalizeShield(
    receipt: TransactionReceipt,
    shieldContract: String,
    commitment: String
) throws -> ShieldResult

struct PrivacyBoostConfig {
    let serverUrl: String
    let wethContractAddress: String
    let appId: String
    let chainId: UInt64?
    let shieldContractAddress: String?
    let teePublicKey: String?
    let persistenceStorage: StorageBackend?
    let persistenceUnlock: UnlockMethod?
    let approvalOnly: Bool
    let idleTtlSecs: UInt64?
    let absoluteTtlSecs: UInt64?
}

struct ChainContextConfig {
    let serverUrl: String
    let chainId: UInt64
    let shieldContractAddress: String?
    let wethContractAddress: String?
    let rpcUrl: String?
    let teePublicKey: String?
    let timeoutMs: UInt64
}

enum KeySource {
    case walletDerived
    case mnemonic(phrase: String)
    case rawSeed(hexSeed: String)
}

enum AuthResult {
    case authenticated(LoginResult)
    case credentialRequired(CredentialChallenge)
    case mnemonicGenerated(mnemonic: String)
    case recoveryRequired(challenge: RecoveryChallenge)
    case accountCreationRequired(challenge: AccountCreationChallenge)
}

struct LoginResult {
    let privacyAddress: String
    let mpk: String
}

struct TokenBalance {
    let tokenAddress: String
    let shieldedBalance: String
    let walletBalance: String
    let symbol: String?
    let decimals: UInt8
}

struct FeeRates {
    let transferFeeFlat: String
    let unshieldFeeBps: UInt16
    let feeSchemaVersion: UInt16?
    let requiresFeeSchemaVersion: UInt16?
    let transferRequiresFeeSchemaVersion: UInt16?
    let unshieldRequiresFeeSchemaVersion: UInt16?
    let transferFeeMode: String?
    let transferFeeBps: UInt16?
    let unshieldFeeMode: String?
    let unshieldFeeFlat: String?
    let gatewayAddress: String?
    let gatewaySelector: String?
    let gatewayFeeMode: String?
    let gatewayFeeFlat: String?
    let gatewayFeeRate: UInt32?
    let gatewayFeeRateDenominator: UInt32?
    let gatewayFeeBase: String?
    let gatewayRequiresFeeSchemaVersion: UInt16?
}

struct ShieldResult {
    let txHash: String
    let commitment: String
    let warning: String?
    let requestId: String       // on-chain shield request id
    let wrapTxHash: String?     // present when native ETH was wrapped
}

struct UnshieldResult {
    let txHash: String
    let fee: String
}

struct TransferResult {
    let requestId: String
    let txHash: String
    let fee: String
    let giftRecord: GiftRecord? // populated by gift funding; persist to refund
    let claimLink: String?      // pbgift:v1:... — populated by gift funding
}

struct Call {
    let to: String
    let value: String
    let data: String
}

struct ShieldFinalizeMeta {
    let shieldContract: String
    let tokenId: UInt16
}

struct PreparedShield {
    let approve: Call?   // ERC-20 approve(pool, amount); nil when managed out of band
    let wrap: Call?      // WETH deposit() wrap; present only when shielding native ETH
    let shield: Call     // the requestDeposit(...) call
    let commitment: String
    let finalize: ShieldFinalizeMeta
}

struct TransactionLog {
    let address: String
    let topics: [String]
    let data: String
}

struct TransactionReceipt {
    let txHash: String
    let status: Bool
    let logs: [TransactionLog]
}

struct Transaction {
    let txHash: String
    let txType: String
    let tokenAddress: String
    let amount: String
    let direction: String
    let senderPubKey: String
    let receiverPubKeys: [String]
    let createdAt: UInt64
}

struct TransactionsResult {
    let data: [Transaction]
    let limit: UInt32
    let next: String?      // cursor for the next page; nil at the end
}

struct TransactionHistoryQuery {
    let txType: String?                 // filter by transaction type
    let tokenId: UInt16?                // registered token id, from getRegisteredTokens()
    let direction: TransactionDirection? // .incoming or .outgoing, relative to the wallet
    let limit: UInt32?                  // page size
    let cursor: String?                 // previous page's next
    let collapseGateway: Bool           // fold each Gateway operation's two rows into one
}

enum TransactionDirection {
    case incoming
    case outgoing
}

struct IdentityResult {
    let mpk: String
    let ethereumAddress: String
    let viewingPublicKeyX: String
    let viewingPublicKeyY: String
    let privacyAddress: String
}

struct ExportedSession {
    let version: UInt32
    let data: String
}

struct Contact {
    let id: String
    let privacyAddress: String?
    let ethAddress: String?
    let nickname: String
    let emoji: String
    let metadata: [String: String]?
    let updatedAt: String
    let decryptionFailed: Bool   // the server could not open this row; show it as unreadable
}

struct CreateContactInput {
    let privacyAddress: String
    let nickname: String
    let ethAddress: String?
    let emoji: String?
    let metadata: [String: String]?
    let clientId: String?        // caller-chosen correlation id echoed back in bulk results
}

// A PATCH field: leave it alone, clear it, or replace it.
enum StringPatch {
    case keep
    case clear
    case set(value: String)
}

enum MetadataPatch {
    case keep
    case clear
    case set(value: [String: String])
}

// Every field is a patch. `.clear` on nickname or emoji throws: the API can
// only replace those two.
struct UpdateContactInput {
    let ethAddress: StringPatch
    let nickname: StringPatch
    let emoji: StringPatch
    let metadata: MetadataPatch
}

struct BulkContactRef {
    let clientId: String?
    let id: String
}

// A contact whose privacy address already exists lands in `skipped` with the existing row's id.
struct BulkContactsResult {
    let created: [BulkContactRef]
    let skipped: [BulkContactRef]
}

struct ContactPage {
    let contacts: [Contact]
    let nextCursor: String?
}

struct TransactionLabel {
    let txHash: String?
    let contactId: String?
    let memo: String?
    let metadata: [String: String]?
    let updatedAt: String
    let decryptionFailed: Bool
}

// A PUT replaces the whole label, so an absent field means "no value".
struct UpsertLabelInput {
    let contactId: String?
    let memo: String?
    let metadata: [String: String]?
}

struct TransactionLabelPage {
    let labels: [TransactionLabel]
    let nextCursor: String?
}

// Selectors for the typed history reads. The `*Json` accessors take the wire
// names ("tvlUsd" / "netApy", "1w" / "1m" / "3m" / "all") instead.
enum EarnHistoryMetric {
    case tvlUsd
    case netApy
}

enum EarnHistoryPeriod {
    case oneWeek
    case oneMonth
    case threeMonths
    case all
}

struct EarnResult {
    let requestId: String
    let action: String              // "deposit" | "redeem"
    let vaultAddress: String
    let inputTokenId: UInt16
    let outputTokenId: UInt16
    let amount: String
    let fee: String
    let expectedOutputAmount: String
    let minOutputAmount: String
    let expiryBlock: UInt64
}

struct EarnVaultCatalog {
    let vaults: [EarnVaultSummary]
    let gateway: GatewayAvailability
}

struct EarnVaultSummary {
    let chainId: UInt64
    let vaultAddress: String
    let asset: EarnVaultAsset       // address, symbol, decimals, logoUri
    let name: String
    let symbol: String
    let description: String?
    let imageUrl: String?
    let apy: EarnApy
    let tvlUsd: Double?
    let liquidity: String?          // smallest unit, decimal string
    let liquidityUsd: Double?
    let fees: EarnFees              // performanceFee, managementFee
    let curators: [EarnCurator]     // name, image, aumUsd
    let warnings: [EarnWarning]     // warningType, level
    let listed: Bool
    let capabilities: EarnVaultCapabilities   // deposit, redeem
    let availability: EarnVaultAvailability   // deposit, redeem: GatewayAvailability
    let metadata: EarnVaultMetadata           // state, updatedAt
    let protocol: String
    let protocolVersion: String
    let updatedAt: String?
}

struct EarnApy {
    let net: Double?                // fractions: 0.05 is 5%
    let netExcludingRewards: Double?
    let net7d: Double?
    let net30d: Double?
    let net90d: Double?
    let rewards: [EarnReward]       // assetAddress, assetSymbol, supplyApr
}

struct GatewayAvailability {
    let state: String
    let canSubmit: Bool
    let reason: String
    let retryable: Bool             // a closed window expected to reopen on its own
    let checkedAt: String?
}

struct EarnVaultDetail {
    let summary: EarnVaultSummary
    let owner: String?
    let curator: String?
    let deployedAt: String?
    let timelockSeconds: UInt64?
    let guardian: String?
    let feeRecipient: String?
    let sharePrice: Double?
    let sharePriceUsd: Double?
    let gateway: GatewayAvailability
}

struct GatewayConfig {
    let enabled: Bool
    let executorAddress: String?
    let adapters: [GatewayAdapterInfo]      // id, version, quoteMode, availability
    let constraints: GatewayConstraints     // calldata, slippage, and expiry limits
    let rescue: GatewayRescueInfo           // cancelDelayBlocks
    let policy: GatewayPolicyInfo
    let availability: GatewayAvailability
}

struct EarnVaultHistory {
    let chainId: UInt64
    let vaultAddress: String
    let protocol: String
    let protocolVersion: String
    let metric: String              // "tvlUsd" | "netApy"
    let period: String
    let interval: String
    let unit: String
    let lookbackHours: Int64?
    let periodAverage: Double?
    let points: [VaultHistoryPoint] // timestamp, value (nil is an upstream gap)
    let metadata: VaultHistoryMetadata      // state, updatedAt
}

struct EarnVaultCharts {
    let tvlUsd: EarnVaultHistory
    let netApy: EarnVaultHistory
}

struct StartaleCampaignProgress {
    let hasDepositedAtLeast10Usd: Bool
    let hasMadeTransfer: Bool
    let campaignTokenId: UInt16?   // nil only when no campaign token is configured
}

protocol WalletDelegate: AnyObject {
    func getAddress() async throws -> String
    func getChainId() async throws -> UInt64
    func signMessage(message: String) async throws -> String
    func signTypedData(typedDataJson: String) async throws -> String
    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String
    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt
}

struct TransactionLog {
    let address: String
    let topics: [String]
    let data: String
}

struct TransactionReceipt {
    let txHash: String
    let status: Bool
    let logs: [TransactionLog]
}

protocol TokenProvider: AnyObject {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse
}

struct TokenResponse {
    let token: String      // JWT access token
    let expiresIn: UInt64  // Token lifetime in seconds
}

class MyTokenProvider: TokenProvider {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse {
        var request = URLRequest(url: URL(string: "https://your-server.com/api/privacy-auth")!)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = loginPayloadJson.data(using: .utf8)

        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
        return TokenResponse(
            token: json["token"] as! String,
            expiresIn: json["expiresIn"] as! UInt64
        )
    }
}

let result = try await sdk.authenticate(
    wallet: walletDelegate,
    tokenProvider: MyTokenProvider()
)

protocol KeychainDelegate: AnyObject {
    func store(key: String, value: Data, requireBiometry: Bool) async throws
    func load(key: String) async throws -> Data?
    func remove(key: String) async throws
    func contains(key: String) async throws -> Bool
    func isAvailable() -> Bool
    func supportsBiometry() -> Bool
}

enum SDKError: Error {
    case notConnected
    case notAuthenticated
    case authenticationFailed(message: String)
    case invalidConfig
    case configError(message: String)
    case networkError(message: String)
    case walletError(message: String)
    case signatureRejected
    case insufficientBalance(message: String)
    case invalidAddress
    case invalidAmount
    case invalidInput(message: String)
    case serializationError(message: String)
    case authServerError(code: String, message: String)
    case shieldError(code: String, message: String)
    case transferError(code: String, message: String)
    case noteError(code: String, message: String)
    case merkleError(code: String, message: String)
    case apiError(code: String, message: String, retryable: Bool)
    case rateLimited(retryAfterMs: UInt64)
    case forbidden(message: String)
    case resourceNotFound(message: String)
    case waitTimeout(requestId: String, waited: String)
    case transactionFailed(requestId: String, message: String)
    case internalError(message: String)
    case transactionReverted(message: String)
    case cryptoError(message: String)
    case stateError(message: String)
    case operationError(message: String)
}

func giftFundToWallet(
    tokenAddress: String,
    amount: String,
    recipientWallet: String,
    refundAfterBlock: UInt64,
    currentBlock: UInt64
) async throws -> TransferResult

func giftFund(
    tokenAddress: String,
    amount: String,
    recipientPrivacyAddress: String,
    recipientWallet: String,
    refundAfterBlock: UInt64,
    currentBlock: UInt64
) async throws -> TransferResult

func giftClaim(index: UInt32, acknowledgeUnknownSender: Bool) async throws -> TransferResult

func giftClaimByCGift(cGift: String, acknowledgeUnknownSender: Bool) async throws -> TransferResult

func giftClaimFromLink(link: String, acknowledgeUnknownSender: Bool) async throws -> TransferResult

func giftRefundByRecord(index: UInt32) async throws -> TransferResult

func giftRefund(
    recipientWallet: String,
    blind: String,
    refundAfterBlock: UInt64,
    tokenId: UInt16,
    amount: String,
    fundingTreeNumber: UInt64,
    giftLeafIndex: UInt64
) async throws -> TransferResult

func getPendingGifts() async throws -> [PendingGift]

func getGiftRecords() -> [GiftRecord]

func decodeGiftLink(link: String) throws -> GiftLinkPreview

struct GiftRecord {
    let recipientWallet: String
    let blind: String
    let refundAfterBlock: UInt64
    let tokenId: UInt16
    let amount: String
    let cGift: String
    let giftNpk: String
    let requestId: String
    let fundingTreeNumber: UInt64?
    let giftLeafIndex: UInt64?
    let status: String?
}

struct PendingGift {
    let index: UInt32
    let treeNumber: UInt64
    let leafIndex: UInt64
    let cGift: String
    let tokenId: UInt16
    let amount: String
    let refundAfterBlock: UInt64
    let recipientWallet: String
}

struct GiftLinkPreview {
    let server: String
    let chainId: UInt64
    let cGift: String
    let recipientWallet: String
    let tokenId: UInt16
    let amount: String
    let refundAfterBlock: UInt64
}

func createPortal(index: UInt32?) async throws -> Portal

func listPortalsPage(cursor: String?, limit: UInt32) async throws -> PortalInfoPage

func listPortalDepositsPage(
    portal: String,
    cursor: String?,
    limit: UInt32
) async throws -> PortalDepositPage

func getPortalStatus(portal: String) async throws -> PortalStatus

func sweepPortal(portal: String, tokenId: UInt16) async throws -> String

func reclaimPortalDeposit(depositId: String) async throws -> String

func withdrawPortal(
    index: UInt32,
    token: String,
    to: String,
    amount: String,
    nonce: String,
    gasLimit: String,
    maxFeePerGas: String,
    maxPriorityFeePerGas: String
) throws -> String

func generatePortalEoa() -> PortalEoa

func encodePortalWithdraw(token: String, to: String, amount: String) throws -> String

func publishPortalRegistry(portal: String, index: UInt32) async throws

func portalDelegateAddress() -> String?

struct Portal {
    let address: String
    let index: UInt32
    let bindH: String
}

struct PortalInfo {
    let address: String
    let index: UInt32
    let status: PortalStatus
}

struct PortalInfoPage {
    let items: [PortalInfo]
    let nextCursor: String?
}

struct PortalStatus {
    let registered: Bool
    let delegated: Bool
    let published: Bool
}

enum PortalDepositState {
    case pendingSweep
    case credited
    case cancellable
    case cancelled
    case unknown
}

struct PortalDeposit {
    let portalDepositId: String
    let portal: String
    let tokenId: UInt16
    let grossAmount: String
    let netAmount: String
    let sweepFeeBps: UInt16  // rate snapshotted when this deposit was swept
    let feeAmount: String    // grossAmount - netAmount
    let state: PortalDepositState
    let requestBlock: UInt64
    let cancellableAtBlock: UInt64
}

struct PortalDepositPage {
    let items: [PortalDeposit]
    let nextCursor: String?
}

struct PortalEoa {
    let privateKey: String  // SECRET — custody it; never persisted by the SDK
    let address: String     // the portal deposit address E
}

protocol ChainReaderDelegate {
    func getBlockNumber() async throws -> UInt64
    func readContract(contractAddress: String, data: String) async throws -> String
}

func setChainReader(reader: ChainReaderDelegate)

func listShieldsByStatus(statuses: [String]) async throws -> [UnsettledShield]

func depositRequestIdsFromTransaction(txHash: String) async throws -> [String]

func getDepositCancellation(depositRequestId: String) async throws -> DepositCancellation

func cancelDeposit(depositRequestId: String) async throws -> String

enum DepositCancelState {
    case cancellable
    case notFound
    case notDepositor
    case alreadyProcessed
    case tooEarly
    case gatewayOrigin
}

struct DepositCancellation {
    let depositRequestId: String   // the queried id, normalized to decimal
    let state: DepositCancelState
    let cancellable: Bool          // true exactly when state is .cancellable
    let depositor: String?         // nil when no escrow exists
    let caller: String             // the address the status was evaluated against
    let tokenId: UInt16
    let totalAmount: String        // escrow that would be refunded; "0" when absent
    let requestBlock: UInt64
    let cancelDelay: UInt64        // the pool's cancelDelay(), in blocks
    let cancellableAtBlock: UInt64 // requestBlock + cancelDelay
    let currentBlock: UInt64       // chain head the status was evaluated at
    let blocksRemaining: UInt64    // 0 once the delay has elapsed
    let reason: String             // human-readable explanation of state
}