`receivePolicy.set`

Sets the receive policy for the calling account. A receive policy controls which TIP-20 tokens and which senders an account accepts. Inbound transfers and mints that violate the policy are not reverted – instead the funds are redirected to the ReceivePolicyGuard and can be reclaimed later (see receivePolicy.claim). Learn more about transfer policies

Usage

The simplest policy uses the built-in 'allow-all' / 'reject-all' sentinels, which map to the protocol's default policy ids (1 and 0).

import { client } from './viem.config'
 
const { receipt } = await client.receivePolicy.setSync({
  senderPolicyId: 'allow-all',
  tokenPolicyId: 'allow-all',
  claimer: 'self',
})
 
console.log('Transaction hash:', receipt.transactionHash)
Transaction hash: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

import { Account, createClient } from 'viem/tempo'
 
export const client = createClient({
  account: Account.fromSecp256k1('0x...'),
})

Restricting senders

Pass a custom policy id (>= 2) as senderPolicyId to control which addresses are allowed to send to you. Create the policy first with policy.create, then derive senderPolicyId from the returned policyId.

import { client } from './viem.config'
 
// 1. Create a whitelist of allowed senders.
const { policyId } = await client.policy.createSync({
  type: 'whitelist',
  addresses: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb'],
})
 
// 2. Only accept inbound transfers from those senders.
await client.receivePolicy.setSync({
  senderPolicyId: policyId,
})

Restricting tokens

tokenPolicyId works the same way, but filters on the token address instead of the sender. Whitelist the tokens you want to accept and reject everything else.

import { client } from './viem.config'
 
// 1. Create a whitelist of allowed tokens.
const { policyId } = await client.policy.createSync({
  type: 'whitelist',
  addresses: ['0x20c0000000000000000000000000000000000001'],
})
 
// 2. Only accept inbound transfers of those tokens (from any sender).
await client.receivePolicy.setSync({
  senderPolicyId: 'allow-all',
  tokenPolicyId: policyId,
})

You can also combine both — e.g. restrict senders and tokens — by passing a custom policy id to each field.

Choosing who can reclaim

When a transfer is blocked the funds are held by the ReceivePolicyGuard. The claimer option controls who may later claim them.

import { client } from './viem.config'
 
// Reclaimable by the originating sender (default).
await client.receivePolicy.setSync({
  senderPolicyId: 'reject-all',
  claimer: 'sender',
})
 
// Reclaimable by the account configuring the policy.
await client.receivePolicy.setSync({
  senderPolicyId: 'reject-all',
  claimer: 'self',
})
 
// Reclaimable by a delegated third party.
await client.receivePolicy.setSync({
  senderPolicyId: 'reject-all',
  claimer: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
})

Asynchronous Usage

The example above uses the setSync variant, which waits for the transaction to be included before returning.

If you are optimizing for performance, you should use the non-sync receivePolicy.set action and wait for inclusion manually:

import { client } from './viem.config'
 
const hash = await client.receivePolicy.set({
  senderPolicyId: 'allow-all',
  tokenPolicyId: 'allow-all',
  claimer: 'self',
})
const receipt = await client.waitForTransactionReceipt({ hash })

Return Type

set

type ReturnType = Hash

Returns the transaction hash.

setSync

type ReturnType = {
  /** TIP-403 policy restricting which senders are allowed. */
  senderPolicyId: 'reject-all' | 'allow-all' | bigint
  /** TIP-403 policy restricting which tokens are allowed. */
  tokenPolicyId: 'reject-all' | 'allow-all' | bigint
  /** Who can reclaim funds blocked by this policy. */
  claimer: 'sender' | 'self' | Address
  /** Account the policy was set for. */
  account: Address
  /** Transaction receipt. */
  receipt: TransactionReceipt
}

Parameters

senderPolicyId (optional)

Type: 'reject-all' | 'allow-all' | bigint
Default: 'allow-all'

TIP-403 policy restricting which senders are allowed.

'reject-all' – built-in policy that rejects every sender (id 0).
'allow-all' – built-in policy that allows every sender (id 1).
bigint – a custom policy id (>= 2), e.g. one returned by policy.create.

tokenPolicyId (optional)

Type: 'reject-all' | 'allow-all' | bigint
Default: 'allow-all'

TIP-403 policy restricting which tokens are allowed. Accepts the same values as senderPolicyId.

claimer (optional)

Type: 'sender' | 'self' | Address
Default: 'sender'

Who can reclaim funds blocked by this policy.

'sender' – the originator of the funds may reclaim them.
'self' – the account configuring the policy may reclaim them.
Address – a delegated third party may reclaim them.

throwOnReceiptRevert (optional, `setSync` only)

Type: boolean
Default: true

Whether to throw if the transaction's receipt status is reverted.

account (optional)

Type: Account | Address

Account that will be used to send the transaction.

feeToken (optional)

Type: Address | bigint

Fee token for the transaction.

Can be an unpaused USD-denominated TIP-20 token address or ID. Use client.fee.validateToken({ token }) to validate a token before submitting a transaction or setting it as a fee preference.

feePayer (optional)

Type: Account | true

Fee payer for the transaction.

Can be a Viem Account, or true if a Fee Payer Service will be used.

gas (optional)

Type: bigint

Gas limit for the transaction.

maxFeePerGas (optional)

Type: bigint

Max fee per gas for the transaction.

maxPriorityFeePerGas (optional)

Type: bigint

Max priority fee per gas for the transaction.

nonce (optional)

Type: number

Nonce for the transaction.

nonceKey (optional)

Type: 'expiring' | bigint

Nonce key for the transaction. Use 'expiring' to use expiring nonces (TIP-1009), which enables concurrent transaction submission without nonce ordering.

validBefore (optional)

Type: number

Unix timestamp before which the transaction must be included.

validAfter (optional)

Type: number

Unix timestamp after which the transaction can be included.

throwOnReceiptRevert (optional)

Type: boolean
Default: true

Whether to throw an error if the transaction receipt indicates a revert. Only applicable to *Sync actions.

Suggest changes to this page

receivePolicy.set