buyTraffic

suspend fun buyTraffic(trafficAmountBytes: Long, receivingValidatorPartyId: String, synchronizerId: String, trackingId: String = java.util.UUID.randomUUID().toString(), expiresAt: Instant = java.time.Instant.now().plusSeconds(600)): ValidatorClient.BuyTrafficRequest

Requests a synchronizer extra-traffic purchase (/v0/wallet/buy-traffic-requests), paid in Amulet from the authenticated user's wallet.

Whose traffic: the sequencer member that gets the bytes is the participant node hosting receivingValidatorPartyId — for a wallet user that is the validator's own participant, bought on the user's behalf (participant-level traffic is shared by every party the validator hosts). Watch it land via ScanClient.memberTrafficStatus for that participant (ScanClient.partyParticipantId resolves it).

This call only creates the request; the validator's wallet automation executes AmuletRules_BuyMemberTraffic asynchronously. Poll buyTrafficStatus with BuyTrafficRequest.trackingId until it reports BuyTrafficStatus.Completed or BuyTrafficStatus.Failed.

The purchase burns Amulet worth bytes × extraTrafficPrice (USD/MB, converted at the open round's amulet price) and must buy at least minTopupAmount bytes — both published in ScanClient.amuletRulesConfig's SynchronizerFeeConfig.

Parameters

trafficAmountBytes

bytes of extra traffic to buy, at least the network's minTopupAmount (the automation rejects smaller requests).

receivingValidatorPartyId

traffic goes to the participant hosting this party — pass the user's wallet party to top up its own validator.

synchronizerId

the synchronizer to buy traffic on (AmuletRulesConfig.activeSynchronizerId).

trackingId

exactly-once key: reuse the same id when retrying a submission that may already have gone through (a duplicate answers 409/429, see ValidatorException.statusCode); use a fresh id for a genuinely new purchase.

expiresAt

when the unexecuted request lapses (compared against ledger time; default 10 minutes out).