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, and enabled per deployment. Gift methods are called directly on the PrivacyBoost instance (sdk below). They may not be present in the checked-in generated Swift bindings, so the code blocks here are illustrative and not verified against the published build.

Sending a gift

The most common case: you know the recipient’s wallet address but they have not joined Privacy Boost. Use giftFundToWallet. Every fund/claim/refund call returns a TransferResult.

// Read the current chain head from your own RPC / chain client.
// Refund deadline: a block height after which you can reclaim an unclaimed gift.
// The min/max delay is advertised from the server's /info endpoint.
let currentBlock: UInt64 = try await myRpcClient.blockNumber()
let refundAfterBlock = currentBlock + 50_000

do {
    let result = try await sdk.giftFundToWallet(
        tokenAddress: "0x...token-address",
        amount: "1000000000000000000", // 1 token, in wei
        recipientWallet: "0xRecipientEoaAddress",
        refundAfterBlock: refundAfterBlock,
        currentBlock: currentBlock
    )
    print("Funded gift: \(result.txHash)")
    if let link = result.claimLink {
        print("Share this claim link with the recipient: \(link)")
    }
    // Persist result.giftRecord so you can refund later (see "Refunding" below).
    if let record = result.giftRecord {
        saveGiftRecord(record)
    }
} catch {
    print("Gift funding failed: \(error)")
}

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. Note the argument label is recipientPrivacyAddress — the 194-char privacy address — alongside the recipient’s wallet:

let result = try await sdk.giftFund(
    tokenAddress: "0x...token-address",
    amount: "1000000000000000000",
    recipientPrivacyAddress: "0x04...recipient-privacy-address", // 194-char privacy address
    recipientWallet: "0xRecipientEoaAddress",
    refundAfterBlock: refundAfterBlock,
    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`	`UInt64`	Yes	Block height after which you may reclaim an unclaimed gift
`currentBlock`	`UInt64`	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 optional gift fields:

struct TransferResult {
    let requestId: String
    let txHash: String
    let fee: String                 // Fee paid (in wei)
    let giftRecord: GiftRecord?     // persist this — it makes the gift refundable
    let 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:

let pending = try await sdk.getPendingGifts()
for gift in pending {
    print("#\(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):
let claimed = try await sdk.giftClaim(index: 0, acknowledgeUnknownSender: true)

// By stable commitment (preferred when the list may change):
let claimed = try await sdk.giftClaimByCGift(
    cGift: pending[0].cGift,
    acknowledgeUnknownSender: true
)

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

let claimed = try await 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.

// Records the SDK persisted for gifts you funded:
let records = sdk.getGiftRecords()

// Refund the one at index 0 (a positional UInt32, not a record value):
let refunded = try await sdk.giftRefundByRecord(index: 0)

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 with no network call — useful to show the recipient what they are about to accept. decodeGiftLink is synchronous and offline (throwing, no await):

let preview = try sdk.decodeGiftLink(link: "pbgift:v1:...")
print(preview.amount, preview.tokenId, preview.recipientWallet, preview.refundAfterBlock)

Types

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
}

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