# From rust-sdk directory
make docs-rust

# Android-specific docs
cargo doc --no-deps -p privacy-boost-android

PrivacyBoost(config: PrivacyBoostConfig)

fun isConnected(): Boolean
fun isAuthenticated(): Boolean

fun authenticate(wallet: WalletDelegate, keySource: KeySource? = null, tokenProvider: TokenProvider? = null): AuthResult

fun submitCredential(credential: String, tokenProvider: TokenProvider? = null): LoginResult

fun logout()

fun clearSession()

fun lock()

fun getPrivacyAddress(): String?
fun getMpk(): String?
fun getWalletAddress(): String?

fun getBalance(tokenAddress: String): TokenBalance

fun getAllBalances(): List<TokenBalance>

fun getFees(tokenAddress: String): FeeRates

fun getGatewayFees(
    tokenAddress: String,
    gatewayAddress: String,
    gatewaySelector: String? = null
): FeeRates

fun shield(tokenAddress: String, amount: String): ShieldResult

fun unshield(tokenAddress: String, amount: String, recipient: String): UnshieldResult

fun send(tokenAddress: String, amount: String, recipientPrivacyAddress: String): TransferResult

fun sendBatch(tokenAddress: String, recipients: List<TransferRecipient>): TransferResult

fun prepareShield(tokenAddress: String, amount: String, recipient: String?): PreparedShield

suspend fun earnDeposit(vaultAddress: String, amount: String, slippageBps: UInt?): EarnResult
suspend fun earnRedeem(vaultAddress: String, amount: String, slippageBps: UInt?): EarnResult

suspend fun listEarnVaults(): EarnVaultCatalog
suspend fun getEarnVault(vaultAddress: String): EarnVaultDetail

val catalog = withContext(Dispatchers.IO) { sdk.listEarnVaults() }
for (vault in catalog.vaults.filter { it.listed }) {
    val apy = vault.apy.net?.let { "%.2f%%".format(it * 100) } ?: "n/a"
    val open = vault.availability.deposit.canSubmit
    println("${vault.name} $apy deposits ${if (open) "open" else "closed"}")
}

suspend fun getGatewayConfig(): GatewayConfig

suspend fun getEarnVaultHistory(
    vaultAddress: String,
    metric: EarnHistoryMetric,
    period: EarnHistoryPeriod? = null
): EarnVaultHistory
suspend fun getEarnVaultCharts(vaultAddress: String, period: EarnHistoryPeriod? = null): EarnVaultCharts

fun getTransactionHistory(
    txType: String?,
    tokenAddress: String?,
    limit: UInt?
): List<Transaction>

fun queryTransactionHistory(query: TransactionHistoryQuery): TransactionsResult

// Incoming transactions for token id 1, 25 per page, gateway operations collapsed
val page = withContext(Dispatchers.IO) {
    sdk.queryTransactionHistory(TransactionHistoryQuery(
        tokenId = 1u,
        direction = TransactionDirection.INCOMING,
        limit = 25u,
        collapseGateway = true
    ))
}
for (tx in page.data) {
    println(tx.txHash)
}
// page.next is the cursor for the following page; null at the end

fun exportSession(): ExportedSession?

fun importSession(session: ExportedSession): Boolean

fun listContacts(limit: UInt? = null, cursor: String? = null): ContactPage

fun createContact(input: CreateContactInput): Contact

fun bulkCreateContacts(contacts: List<CreateContactInput>): BulkContactsResult

fun updateContact(id: String, input: UpdateContactInput): Contact

fun deleteContact(id: String)

fun listLabels(limit: UInt? = null, cursor: String? = null): TransactionLabelPage

fun upsertLabel(txHash: String, input: UpsertLabelInput): TransactionLabel

fun deleteLabel(txHash: String)

withContext(Dispatchers.IO) {
    // Save a contact, then label a transfer to them.
    val alice = sdk.createContact(CreateContactInput(
        privacyAddress = "0x04...alice",
        nickname = "Alice",
        ethAddress = "0x1234...abcd",
        metadata = mapOf("team" to "design")
    ))

    sdk.upsertLabel(transfer.txHash, UpsertLabelInput(
        contactId = alice.id,
        memo = "Dinner split"
    ))

    // Later: clear the ETH address and keep everything else.
    sdk.updateContact(alice.id, UpdateContactInput(
        ethAddress = StringPatch.Clear,
        nickname = StringPatch.Keep,
        emoji = StringPatch.Keep,
        metadata = MetadataPatch.Keep
    ))

    // Page through contacts.
    var cursor: String? = null
    do {
        val page = sdk.listContacts(limit = 50u, cursor = cursor)
        page.contacts
            .filterNot { it.decryptionFailed }
            .forEach { println("${it.nickname} ${it.privacyAddress ?: ""}") }
        cursor = page.nextCursor
    } while (cursor != null)
}

fun getStartaleCampaignProgress(): StartaleCampaignProgress

val progress = withContext(Dispatchers.IO) { sdk.getStartaleCampaignProgress() }
if (progress.hasDepositedAtLeast10Usd) missions.markComplete(Mission.Deposit)
if (progress.hasMadeTransfer) missions.markComplete(Mission.Transfer)

fun resolveIdentity(identifier: String): IdentityResult

fun createChainContext(config: ChainContextConfig): ChainContextHandle

fun isValidPrivacyAddress(address: String): Boolean
fun isValidAddress(address: String): Boolean
fun parseAmount(amount: String, decimals: UByte): String
fun formatAmount(wei: String, decimals: UByte): String

fun chainId(): ULong
fun isAuthenticated(): Boolean
fun isRegistered(): Boolean
fun authenticate(wallet: WalletDelegate, externalToken: String? = null): LoginResult
fun clearSession()

// Transactions
fun shield(tokenAddress: String, amount: String): ShieldResult
fun prepareShield(tokenAddress: String, amount: String, recipient: String?): PreparedShield
fun unshield(tokenAddress: String, amount: String, recipient: String): UnshieldResult
fun send(tokenAddress: String, amount: String, recipientPrivacyAddress: String): TransferResult
fun sendBatch(tokenAddress: String, recipients: List<TransferRecipient>): TransferResult
fun unwrapWeth(amount: String, recipient: String): String
fun consolidateNotes(tokenAddress: String, maxRounds: UInt): ConsolidateResult

// Balances, tokens, and fees
fun getBalance(tokenAddress: String): TokenBalance
fun getAllBalances(): List<TokenBalance>
fun getRegisteredTokens(): List<RegisteredToken>
fun getTokenByAddress(address: String): RegisteredToken
fun getFees(tokenAddress: String): FeeRates
fun getGatewayFees(tokenAddress: String, gatewayAddress: String, gatewaySelector: String? = null): FeeRates

// Status and history
fun getShieldStatus(requestId: String): ShieldStatus
fun getTransferStatus(id: String): TransactionStatus
fun getUnshieldStatus(id: String): TransactionStatus
fun getTransactionHistory(txType: String?, limit: UInt?, cursor: String?): TransactionsResult
fun getCollapsedTransactionHistory(txType: String?, limit: UInt?, cursor: String?): TransactionsResult
fun queryTransactionHistory(query: TransactionHistoryQuery): TransactionsResult
fun getUnspentNotes(tokenAddress: String?): List<UnspentNote>

// Pending transactions
fun addPendingTransaction(tx: PendingTransaction)
fun getPendingTransactions(): List<PendingTransaction>
fun getAllPendingTransactions(): List<PendingTransaction>
fun refreshPendingTransactions(): UInt
fun refreshPendingTransactionsDetailed(): RefreshPendingSummary
fun waitForPreconfirmation(requestId: String, timeoutMs: ULong): PendingTransaction
fun waitForFinality(requestId: String, timeoutMs: ULong): PendingTransaction

fun sdkVersion(): String
fun generateMnemonic(): String
fun registerKeychainDelegate(delegate: KeychainDelegate, service: String? = null)
fun hasKeychainDelegate(): Boolean

fun buildShieldPayload(
    tokenAddress: String,
    amount: String,
    recipient: String,
    tokenId: UShort,
    shieldContractAddress: String,
    wethContractAddress: String?,
    teePublicKey: String,
    minShieldAmount: String?,
    emitApprove: Boolean
): PreparedShield

fun finalizeShield(
    receipt: TransactionReceipt,
    shieldContract: String,
    commitment: String
): ShieldResult

data class PrivacyBoostConfig(
    val serverUrl: String,
    val wethContractAddress: String,
    val appId: String,
    val chainId: ULong? = null,
    val shieldContractAddress: String? = null,
    val teePublicKey: String? = null,
    val persistenceStorage: StorageBackend? = null,
    val persistenceUnlock: UnlockMethod? = null,
    val approvalOnly: Boolean = false,
    val idleTtlSecs: ULong? = null,
    val absoluteTtlSecs: ULong? = null
)

data class ChainContextConfig(
    val serverUrl: String,
    val chainId: ULong,
    val shieldContractAddress: String?,
    val wethContractAddress: String?,
    val rpcUrl: String?,
    val teePublicKey: String?,
    val timeoutMs: ULong
)

sealed class KeySource {
    object WalletDerived : KeySource()
    data class Mnemonic(val phrase: String) : KeySource()
    data class RawSeed(val hexSeed: String) : KeySource()
}

sealed class AuthResult {
    data class Authenticated(val loginResult: LoginResult) : AuthResult()
    data class CredentialRequired(val challenge: CredentialChallenge) : AuthResult()
    data class MnemonicGenerated(val mnemonic: String) : AuthResult()
    data class RecoveryRequired(val challenge: RecoveryChallenge) : AuthResult()
    data class AccountCreationRequired(val challenge: AccountCreationChallenge) : AuthResult()
}

data class LoginResult(
    val privacyAddress: String,
    val mpk: String
)

data class TokenBalance(
    val tokenAddress: String,
    val shieldedBalance: String,
    val walletBalance: String,
    val symbol: String?,
    val decimals: UByte
)

data class FeeRates(
    val transferFeeFlat: String,
    val unshieldFeeBps: UShort,
    val feeSchemaVersion: UShort?,
    val requiresFeeSchemaVersion: UShort?,
    val transferRequiresFeeSchemaVersion: UShort?,
    val unshieldRequiresFeeSchemaVersion: UShort?,
    val transferFeeMode: String?,
    val transferFeeBps: UShort?,
    val unshieldFeeMode: String?,
    val unshieldFeeFlat: String?,
    val gatewayAddress: String?,
    val gatewaySelector: String?,
    val gatewayFeeMode: String?,
    val gatewayFeeFlat: String?,
    val gatewayFeeRate: UInt?,
    val gatewayFeeRateDenominator: UInt?,
    val gatewayFeeBase: String?,
    val gatewayRequiresFeeSchemaVersion: UShort?
)

data class ShieldResult(
    val txHash: String,
    val commitment: String,
    val warning: String?,
    val requestId: String,      // on-chain shield request id
    val wrapTxHash: String?     // present when native ETH was wrapped
)

data class UnshieldResult(
    val txHash: String,
    val fee: String
)

data class TransferResult(
    val requestId: String,
    val txHash: String,
    val fee: String,
    val giftRecord: GiftRecord?, // populated by gift funding; null for an ordinary send()
    val claimLink: String?       // pbgift:v1:... populated by gift funding
)

data class Call(
    val to: String,
    val value: String,
    val data: String
)

data class ShieldFinalizeMeta(
    val shieldContract: String,
    val tokenId: UShort
)

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

data class TransactionLog(
    val address: String,
    val topics: List<String>,
    val data: String
)

data class TransactionReceipt(
    val txHash: String,
    val status: Boolean,
    val logs: List<TransactionLog>
)

data class Transaction(
    val txHash: String,
    val txType: String,
    val tokenAddress: String,
    val amount: String,
    val direction: String,
    val senderPubKey: String,
    val receiverPubKeys: List<String>,
    val createdAt: ULong
)

data class TransactionsResult(
    val data: List<Transaction>,
    val limit: UInt,
    val next: String?      // cursor for the next page; null at the end
)

data class TransactionHistoryQuery(
    val txType: String? = null,                 // filter by transaction type
    val tokenId: UShort? = null,                // registered token id, from getRegisteredTokens()
    val direction: TransactionDirection? = null, // relative to the wallet
    val limit: UInt? = null,                    // page size
    val cursor: String? = null,                 // previous page's next
    val collapseGateway: Boolean = false        // fold each Gateway operation's two rows into one
)

enum class TransactionDirection { INCOMING, OUTGOING }

data class IdentityResult(
    val mpk: String,
    val ethereumAddress: String,
    val viewingPublicKeyX: String,
    val viewingPublicKeyY: String,
    val privacyAddress: String
)

data class ExportedSession(
    val version: UInt,
    val data: String
)

data class Contact(
    val id: String,
    val privacyAddress: String?,
    val ethAddress: String?,
    val nickname: String,
    val emoji: String,
    val metadata: Map<String, String>?,
    val updatedAt: String,
    val decryptionFailed: Boolean   // the server could not open this row; show it as unreadable
)

data class CreateContactInput(
    val privacyAddress: String,
    val nickname: String,
    val ethAddress: String? = null,
    val emoji: String? = null,
    val metadata: Map<String, String>? = null,
    val clientId: String? = null    // caller-chosen correlation id echoed back in bulk results
)

// A PATCH field: leave it alone, clear it, or replace it.
sealed class StringPatch {
    object Keep : StringPatch()
    object Clear : StringPatch()
    data class Set(val value: String) : StringPatch()
}

sealed class MetadataPatch {
    object Keep : MetadataPatch()
    object Clear : MetadataPatch()
    data class Set(val value: Map<String, String>) : MetadataPatch()
}

// Every field is a patch. `Clear` on nickname or emoji throws: the API can
// only replace those two.
data class UpdateContactInput(
    val ethAddress: StringPatch,
    val nickname: StringPatch,
    val emoji: StringPatch,
    val metadata: MetadataPatch
)

data class BulkContactRef(
    val clientId: String?,
    val id: String
)

// A contact whose privacy address already exists lands in `skipped` with the existing row's id.
data class BulkContactsResult(
    val created: List<BulkContactRef>,
    val skipped: List<BulkContactRef>
)

data class ContactPage(
    val contacts: List<Contact>,
    val nextCursor: String?
)

data class TransactionLabel(
    val txHash: String?,
    val contactId: String?,
    val memo: String?,
    val metadata: Map<String, String>?,
    val updatedAt: String,
    val decryptionFailed: Boolean
)

// A PUT replaces the whole label, so an absent field means "no value".
data class UpsertLabelInput(
    val contactId: String?,
    val memo: String?,
    val metadata: Map<String, String>?
)

data class TransactionLabelPage(
    val labels: List<TransactionLabel>,
    val nextCursor: String?
)

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

enum class EarnHistoryPeriod { ONE_WEEK, ONE_MONTH, THREE_MONTHS, ALL }

data class EarnResult(
    val requestId: String,
    val action: String,              // "deposit" | "redeem"
    val vaultAddress: String,
    val inputTokenId: UShort,
    val outputTokenId: UShort,
    val amount: String,
    val fee: String,
    val expectedOutputAmount: String,
    val minOutputAmount: String,
    val expiryBlock: ULong,
)

data class EarnVaultCatalog(
    val vaults: List<EarnVaultSummary>,
    val gateway: GatewayAvailability,
)

data class EarnVaultSummary(
    val chainId: ULong,
    val vaultAddress: String,
    val asset: EarnVaultAsset,       // address, symbol, decimals, logoUri
    val name: String,
    val symbol: String,
    val description: String?,
    val imageUrl: String?,
    val apy: EarnApy,
    val tvlUsd: Double?,
    val liquidity: String?,          // smallest unit, decimal string
    val liquidityUsd: Double?,
    val fees: EarnFees,              // performanceFee, managementFee
    val curators: List<EarnCurator>,     // name, image, aumUsd
    val warnings: List<EarnWarning>,     // warningType, level
    val listed: Boolean,
    val capabilities: EarnVaultCapabilities,   // deposit, redeem
    val availability: EarnVaultAvailability,   // deposit, redeem: GatewayAvailability
    val metadata: EarnVaultMetadata,           // state, updatedAt
    val protocol: String,
    val protocolVersion: String,
    val updatedAt: String?,
)

data class EarnApy(
    val net: Double?,                // fractions: 0.05 is 5%
    val netExcludingRewards: Double?,
    val net7d: Double?,
    val net30d: Double?,
    val net90d: Double?,
    val rewards: List<EarnReward>,       // assetAddress, assetSymbol, supplyApr
)

data class GatewayAvailability(
    val state: String,
    val canSubmit: Boolean,
    val reason: String,
    val retryable: Boolean,             // a closed window expected to reopen on its own
    val checkedAt: String?,
)

data class EarnVaultDetail(
    val summary: EarnVaultSummary,
    val owner: String?,
    val curator: String?,
    val deployedAt: String?,
    val timelockSeconds: ULong?,
    val guardian: String?,
    val feeRecipient: String?,
    val sharePrice: Double?,
    val sharePriceUsd: Double?,
    val gateway: GatewayAvailability,
)

data class GatewayConfig(
    val enabled: Boolean,
    val executorAddress: String?,
    val adapters: List<GatewayAdapterInfo>,      // id, version, quoteMode, availability
    val constraints: GatewayConstraints,     // calldata, slippage, and expiry limits
    val rescue: GatewayRescueInfo,           // cancelDelayBlocks
    val policy: GatewayPolicyInfo,
    val availability: GatewayAvailability,
)

data class EarnVaultHistory(
    val chainId: ULong,
    val vaultAddress: String,
    val protocol: String,
    val protocolVersion: String,
    val metric: String,              // "tvlUsd" | "netApy"
    val period: String,
    val interval: String,
    val unit: String,
    val lookbackHours: Long?,
    val periodAverage: Double?,
    val points: List<VaultHistoryPoint>, // timestamp, value (null is an upstream gap)
    val metadata: VaultHistoryMetadata,      // state, updatedAt
)

data class EarnVaultCharts(
    val tvlUsd: EarnVaultHistory,
    val netApy: EarnVaultHistory,
)

data class StartaleCampaignProgress(
    val hasDepositedAtLeast10Usd: Boolean,
    val hasMadeTransfer: Boolean,
    val campaignTokenId: UShort?   // null only when no campaign token is configured
)

interface WalletDelegate {
    suspend fun getAddress(): String
    suspend fun getChainId(): ULong
    suspend fun signMessage(message: String): String
    suspend fun signTypedData(typedDataJson: String): String
    suspend fun sendTransaction(toAddress: String, value: String, data: String): String
    suspend fun waitForTransactionReceipt(txHash: String): TransactionReceipt
}

data class TransactionLog(
    val address: String,
    val topics: List<String>,
    val data: String
)

data class TransactionReceipt(
    val txHash: String,
    val status: Boolean,
    val logs: List<TransactionLog>
)

interface TokenProvider {
    suspend fun getToken(loginPayloadJson: String): TokenResponse
}

data class TokenResponse(
    val token: String,     // JWT access token
    val expiresIn: ULong   // Token lifetime in seconds
)

class MyTokenProvider : TokenProvider {
    override suspend fun getToken(loginPayloadJson: String): TokenResponse {
        val response = yourHttpClient.post("https://your-server.com/api/privacy-auth") {
            contentType(ContentType.Application.Json)
            setBody(loginPayloadJson)
        }
        val json = Json.parseToJsonElement(response.bodyAsText()).jsonObject
        return TokenResponse(
            token = json["token"]!!.jsonPrimitive.content,
            expiresIn = json["expiresIn"]!!.jsonPrimitive.long.toULong()
        )
    }
}

val result = sdk.authenticate(
    wallet = walletDelegate,
    tokenProvider = MyTokenProvider()
)

interface KeychainDelegate {
    suspend fun store(key: String, value: ByteArray, requireBiometry: Boolean)
    suspend fun load(key: String): ByteArray?
    suspend fun remove(key: String)
    suspend fun contains(key: String): Boolean
    fun isAvailable(): Boolean
    fun supportsBiometry(): Boolean
}

sealed class SDKError : Exception() {
    object NotConnected : SDKError()
    object NotAuthenticated : SDKError()
    data class AuthenticationFailed(override val message: String) : SDKError()
    object InvalidConfig : SDKError()
    data class ConfigError(override val message: String) : SDKError()
    data class NetworkError(override val message: String) : SDKError()
    data class WalletError(override val message: String) : SDKError()
    object SignatureRejected : SDKError()
    data class InsufficientBalance(override val message: String) : SDKError()
    object InvalidAddress : SDKError()
    object InvalidAmount : SDKError()
    data class InvalidInput(override val message: String) : SDKError()
    data class SerializationError(override val message: String) : SDKError()
    data class AuthServerError(val code: String, override val message: String) : SDKError()
    data class ShieldError(val code: String, override val message: String) : SDKError()
    data class TransferError(val code: String, override val message: String) : SDKError()
    data class NoteError(val code: String, override val message: String) : SDKError()
    data class MerkleError(val code: String, override val message: String) : SDKError()
    data class ApiError(val code: String, override val message: String, val retryable: Boolean) : SDKError()
    data class RateLimited(val retryAfterMs: ULong) : SDKError()
    data class Forbidden(override val message: String) : SDKError()
    data class ResourceNotFound(override val message: String) : SDKError()
    data class WaitTimeout(val requestId: String, val waited: String) : SDKError()
    data class TransactionFailed(val requestId: String, override val message: String) : SDKError()
    data class InternalError(override val message: String) : SDKError()
    data class TransactionReverted(override val message: String) : SDKError()
    data class CryptoError(override val message: String) : SDKError()
    data class StateError(override val message: String) : SDKError()
    data class OperationError(override val message: String) : SDKError()
}

fun giftFundToWallet(
    tokenAddress: String,
    amount: String,
    recipientWallet: String,
    refundAfterBlock: ULong,
    currentBlock: ULong
): TransferResult

fun giftFund(
    tokenAddress: String,
    amount: String,
    recipientPrivacyAddress: String,
    recipientWallet: String,
    refundAfterBlock: ULong,
    currentBlock: ULong
): TransferResult

fun giftClaim(index: UInt, acknowledgeUnknownSender: Boolean): TransferResult

fun giftClaimByCGift(cGift: String, acknowledgeUnknownSender: Boolean): TransferResult

fun giftClaimFromLink(link: String, acknowledgeUnknownSender: Boolean): TransferResult

fun giftRefundByRecord(index: UInt): TransferResult

fun giftRefund(
    recipientWallet: String,
    blind: String,
    refundAfterBlock: ULong,
    tokenId: UShort,
    amount: String,
    fundingTreeNumber: ULong,
    giftLeafIndex: ULong
): TransferResult

fun getPendingGifts(): List<PendingGift>

fun getGiftRecords(): List<GiftRecord>

fun decodeGiftLink(link: String): GiftLinkPreview

data class GiftRecord(
    val recipientWallet: String,
    val blind: String,
    val refundAfterBlock: ULong,
    val tokenId: UShort,
    val amount: String,
    val cGift: String,
    val giftNpk: String,
    val requestId: String,
    val fundingTreeNumber: ULong?,
    val giftLeafIndex: ULong?,
    val status: String?
)

data class PendingGift(
    val index: UInt,
    val treeNumber: ULong,
    val leafIndex: ULong,
    val cGift: String,
    val tokenId: UShort,
    val amount: String,
    val refundAfterBlock: ULong,
    val recipientWallet: String
)

data class GiftLinkPreview(
    val server: String,
    val chainId: ULong,
    val cGift: String,
    val recipientWallet: String,
    val tokenId: UShort,
    val amount: String,
    val refundAfterBlock: ULong
)

data class TransferResult(
    val requestId: String,
    val txHash: String,
    val fee: String,
    val giftRecord: GiftRecord?, // present on a fund; persist it to refund later
    val claimLink: String?       // pbgift:v1:... present on a wallet-bound fund
)

fun publishPortalRegistry(portal: String, index: UInt)

fun portalDelegateAddress(): String?

fun createPortal(index: UInt?): Portal
fun listPortalsPage(cursor: String?, limit: UInt): PortalInfoPage
fun listPortalDepositsPage(portal: String, cursor: String?, limit: UInt): PortalDepositPage
fun getPortalStatus(portal: String): PortalStatus
fun sweepPortal(portal: String, tokenId: UShort): String
fun reclaimPortalDeposit(depositId: String): String
fun withdrawPortal(
    index: UInt,
    token: String,
    to: String,
    amount: String,
    nonce: String,
    gasLimit: String,
    maxFeePerGas: String,
    maxPriorityFeePerGas: String
): String

fun generatePortalEoa(): PortalEoa
fun encodePortalWithdraw(token: String, to: String, amount: String): String

data class Portal(
    val address: String,
    val index: UInt,
    val bindH: String
)

data class PortalInfo(
    val address: String,
    val index: UInt,
    val status: PortalStatus
)

data class PortalInfoPage(
    val items: List<PortalInfo>,
    val nextCursor: String?
)

data class PortalStatus(
    val registered: Boolean,
    val delegated: Boolean,
    val published: Boolean
)

enum class PortalDepositState {
    PendingSweep,
    Credited,
    Cancellable,
    Cancelled,
    Unknown
}

data class PortalDeposit(
    val portalDepositId: String,
    val portal: String,
    val tokenId: UShort,
    val grossAmount: String,
    val netAmount: String,
    val sweepFeeBps: UShort, // rate snapshotted when this deposit was swept
    val feeAmount: String,   // grossAmount - netAmount
    val state: PortalDepositState,
    val requestBlock: ULong,
    val cancellableAtBlock: ULong
)

data class PortalDepositPage(
    val items: List<PortalDeposit>,
    val nextCursor: String?
)

data class PortalEoa(
    val privateKey: String, // SECRET — custody and sign with it; never persisted by the SDK
    val address: String     // the portal deposit address E
)

interface ChainReaderDelegate {
    suspend fun getBlockNumber(): ULong
    suspend fun readContract(contractAddress: String, data: String): String
}

fun setChainReader(reader: ChainReaderDelegate)

fun listShieldsByStatus(statuses: List<String>): List<UnsettledShield>

fun depositRequestIdsFromTransaction(txHash: String): List<String>

fun getDepositCancellation(depositRequestId: String): DepositCancellation

fun cancelDeposit(depositRequestId: String): String

enum class DepositCancelState {
    Cancellable,
    NotFound,
    NotDepositor,
    AlreadyProcessed,
    TooEarly,
    GatewayOrigin
}

data class DepositCancellation(
    val depositRequestId: String,   // the queried id, normalized to decimal
    val state: DepositCancelState,
    val cancellable: Boolean,       // true exactly when state is Cancellable
    val depositor: String?,         // null when no escrow exists
    val caller: String,             // the address the status was evaluated against
    val tokenId: UShort,
    val totalAmount: String,        // escrow that would be refunded; "0" when absent
    val requestBlock: ULong,
    val cancelDelay: ULong,         // the pool's cancelDelay(), in blocks
    val cancellableAtBlock: ULong,  // requestBlock + cancelDelay
    val currentBlock: ULong,        // chain head the status was evaluated at
    val blocksRemaining: ULong,     // 0 once the delay has elapsed
    val reason: String              // human-readable explanation of state
)