Claimable Transfers (Gifts)

Send shielded funds to an Ethereum wallet address that has not registered with Privacy Boost yet. The recipient claims by proving ownership of that address; you reclaim the funds if they never do. See Claimable Transfers for the concept and trust model.

Preview feature — pending external audit. Claimable transfers are implemented across the protocol and SDK but have not completed external security audit, and the feature is enabled per deployment. Gift support is advertised by the server’s /info (through its gift refund-delay bounds); gate production use on your own review.

Sending a gift

The most common case: you know the recipient’s wallet address but they have not joined Privacy Boost. Use giftFundToWallet. The refund deadline is a block height after which you can reclaim an unclaimed gift; the min/max delay is advertised from the server’s /info endpoint. Pass the current chain head as currentBlock so the SDK can pre-validate the refund delay before submitting.

try {
    val result = withContext(Dispatchers.IO) {
        sdk.giftFundToWallet(
            tokenAddress = "0x...token-address",
            amount = "1000000000000000000", // 1 token, in wei
            recipientWallet = "0xRecipientEoaAddress",
            refundAfterBlock = currentBlock + 50_000UL,
            currentBlock = currentBlock
        )
    }
    println("Funded gift: ${result.txHash}")
    println("Share this claim link with the recipient: ${result.claimLink}")

    // Persist result.giftRecord so you can refund later (see "Refunding" below).
    saveGiftRecord(result.giftRecord)
} catch (e: SDKError) {
    println("Gift funding failed: $e")
}

If the recipient is already a Privacy Boost user, fund with their privacy address too (giftFund) so the gift ciphertext is sealed to their viewing key for the smoothest discovery:

val result = withContext(Dispatchers.IO) {
    sdk.giftFund(
        tokenAddress = "0x...token-address",
        amount = "1000000000000000000",
        recipientPrivacyAddress = "0x04...recipient-privacy-address", // 194-char privacy address
        recipientWallet = "0xRecipientEoaAddress",
        refundAfterBlock = currentBlock + 50_000UL,
        currentBlock = currentBlock
    )
}

Funding parameters

Parameter	Type	Required	Description
`tokenAddress`	`String`	Yes	Token contract address
`amount`	`String`	Yes	Amount in wei (smallest unit)
`recipientPrivacyAddress`	`String`	`giftFund` only	Recipient’s 194-char privacy address (the ciphertext’s ECDH target)
`recipientWallet`	`String`	Yes	Recipient’s Ethereum address the gift binds to (may be unregistered)
`refundAfterBlock`	`ULong`	Yes	Block height after which you may reclaim an unclaimed gift
`currentBlock`	`ULong`	Yes	Current chain head; pre-validates the refund delay before submitting

The gift binds irrevocably to recipientWallet. A wrong-but-valid address can be claimed by whoever controls it, and only an unclaimed gift is refundable. Show the exact checksummed address and require explicit confirmation before funding.

Funding result

giftFund / giftFundToWallet return a TransferResult carrying two gift fields in addition to the usual transfer fields:

data class TransferResult(
    val requestId: String,
    val txHash: String,
    val fee: String,
    val giftRecord: GiftRecord?, // persist this — it makes the gift refundable
    val claimLink: String?       // pbgift:v1:... — share with the recipient
)

result.claimLink is a pbgift:v1:... string that carries the encrypted opening the recipient needs. Share it out of band (message, QR code). Treat it like a password — it reveals the gift’s amount and recipient to anyone who reads it.

Claiming a gift

The recipient registers Privacy Boost with the same wallet address, then claims. List the pending gifts addressed to the authenticated wallet:

val pending = withContext(Dispatchers.IO) {
    sdk.getPendingGifts()
}
for (gift in pending) {
    println("#${gift.index}: ${gift.amount} of token ${gift.tokenId}")
}

Claim one by its position in that list, or — more robustly — by its stable commitment cGift (the list can shift as gifts settle):

// By index (positional):
withContext(Dispatchers.IO) {
    sdk.giftClaim(index = 0u, acknowledgeUnknownSender = true)
}

// By stable commitment (preferred when the list may change):
withContext(Dispatchers.IO) {
    sdk.giftClaimByCGift(cGift = pending[0].cGift, acknowledgeUnknownSender = true)
}

Or claim straight from a claim link, without a server lookup first:

withContext(Dispatchers.IO) {
    sdk.giftClaimFromLink(link = "pbgift:v1:...", acknowledgeUnknownSender = true)
}

acknowledgeUnknownSender must be true to claim. The hidden-sender model cannot reveal who funded a gift, so the recipient explicitly acknowledges accepting funds from an unknown sender. Surface this as a consent prompt.

A successful claim re-mints the gift into a normal shielded note — from then on it behaves like any other note in the recipient’s balance.

Refunding an unclaimed gift

A claim and a refund spend the same nullifier, so only one can ever settle. After the refund deadline passes, reclaim an unclaimed gift using the local record you saved at funding time. giftRefundByRecord takes the record’s index:

// Records the SDK persisted for gifts you funded:
val records = withContext(Dispatchers.IO) {
    sdk.getGiftRecords()
}

// Refund the one at index 0:
withContext(Dispatchers.IO) {
    sdk.giftRefundByRecord(index = 0u)
}

Gift records are what make a gift refundable. They are included in an exported session, so persisting and restoring the session keeps your unclaimed gifts refundable across restarts. If you ever lose the record, you can still refund by supplying every field manually via giftRefund(recipientWallet, blind, refundAfterBlock, tokenId, amount, fundingTreeNumber, giftLeafIndex).

Previewing a claim link offline

Decode a claim link into a preview without any network call — useful to show the recipient what they are about to accept. decodeGiftLink is synchronous and throwing (it works fully offline), so it does not need withContext:

val preview = sdk.decodeGiftLink(link = "pbgift:v1:...")
println("${preview.amount} of token ${preview.tokenId} to ${preview.recipientWallet}, refundable after ${preview.refundAfterBlock}")

Types

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
)

A third funding mode, giftFundSecretBearer, binds a gift to a secret instead of a wallet so it can be claimed before the recipient has any wallet. It is experimental, disabled by default, and a bearer instrument (whoever holds the link can claim). See the concept page before considering it.

Quickstart

Setup

SDKs

Claimable transfers

Claimable Transfers (Gifts)

Sending a gift

Funding parameters

Funding result

Claiming a gift

Refunding an unclaimed gift

Previewing a claim link offline

Types

​Claimable Transfers (Gifts)

​Sending a gift

​Funding parameters

​Funding result

​Sharing the claim link

​Claiming a gift

​Refunding an unclaimed gift

​Previewing a claim link offline

​Types

Claimable Transfers (Gifts)

Sending a gift

Funding parameters

Funding result

Sharing the claim link

Claiming a gift

Refunding an unclaimed gift

Previewing a claim link offline

Types