Asset Retrieval

The One-Time Actions docs are under active development and will be subject to changes.

There are two locations assets are stored within the Boost Protocol, budgets and incentives. Both budgets and incentives only allow authorized users to retrieve funds, requiring the sender to either be the owner, or have the Roles.MANAGER

Retrieve from Budget

`clawback`

The clawback function is used to reclaim available funds from the budget. Can only be called by owner or admin.

await budget.clawback({
  amount: 0n,
  asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
  target: account.address, // Address to receive the funds
});

Using clawback with 0n will reclaim all available funds for the given asset.
Use the zero address (0x0000000000000000000000000000000000000000) to clawback native assets (ie. ETH).

Parameters

FungibleTransferPayload

required

Show properties

bigint

required

The amount of tokens to transfer.

string

required

The address of the asset. Use zero address (0x0) for ETH transfers.

string

required

The address to receive the funds.

Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>

Optional parameters to pass to the underlying writeContract method. Checkout wagmi’s documentation for more information. address, args, functionName, abi are handled for you under the hood.

Returns

boolean

Returns true if the clawback was successful.

`disburse`

Transfers available funds from the budget to a specified recipient. You must have the manager, admin or owner role to call this function.

The disburse method is authorized for the MANAGER role. Be aware that this allows a manager to disburse funds from the budget at will. Make sure you trust the manager before giving them authorization.

import { parseUnits } from "viem";

await budget.disburse({
  amount: parseUnits('1', 18),
  asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
  target: account.address, // Address to receive the funds
});

Parameters

FungibleTransferPayload

required

Show properties

bigint

required

The amount of tokens to transfer.

string

required

The address of the asset. Use zero address (0x0) for ETH transfers.

string

required

The address to receive the funds.

Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>

Returns

boolean

Returns true if the disbursement was successful.

`disburseBatch`

Transfers available funds from the budget to a list of specified recipients. You must have the manager, admin or owner role to call this function. This method is more gas-efficient for multiple transfers.

import { parseUnits } from "viem";

await budget.disburseBatch([
  {
    amount: parseUnits('1', 18),
    asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
    target: recipient1.address, // Address to receive the funds
  },
  {
    amount: parseUnits('1', 18),
    asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
    target: recipient2.address, // Address to receive the funds
  },
]);

Parameters

FungibleTransferPayload[]

required

Show properties

bigint

required

The amount of tokens to transfer.

string

required

The address of the asset. Use zero address (0x0) for ETH transfers.

string

required

The address to receive the funds.

Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>

Returns

boolean

Returns true if the disbursement was successful.

Retrieve from Incentive

`clawbackFromTarget`

The clawback function allows authorized users (admin or manager) to reclaim assets from a Boost’s incentive back to its associated budget.

The amount reclaimed will be subject to protocol fee collection, so attempting to reclaim an amount where reclaimAmount + calculatedProtocolFee > incentiveBalance will revert with an InsufficientFunds error.

For ERC20Incentive, the amount specified in the clawback data must be an exact multiple of the reward value set in the incentive. Otherwise, the transaction will fail.

Depending on the type of incentive, calculating the clawback amount will be different.

ERC20Incentive
Variable Incentives

// Example for fixed-reward ERC20 incentives
const boost = await core.getBoost(0n)
const budget = boost.budget
const incentiveIndex = 0
const incentive = boost.incentives.at(incentiveIndex)

if (incentive instanceof ERC20Incentive) {
  // Calculate exact amount to clawback based on remaining claims
  const remainingClaims = await incentive.getRemainingClaimPotential()
  const rewardValue = await incentive.reward()
  const clawbackAmount = remainingClaims * rewardValue

  await budget.clawbackFromTarget(
    core.assertValidAddress(),
    incentive.buildClawbackData(clawbackAmount),
    boost.id,
    incentiveIndex
  );
}

// Example for variable-reward incentives
const boost = await core.getBoost(0n)
const budget = boost.budget
const incentiveIndex = 0
const incentive = boost.incentives.at(incentiveIndex)

if (incentive instanceof ERC20VariableIncentive ||
    incentive instanceof ERC20VariableCriteriaIncentive) {
  // For variable incentives, we can directly get the remaining claimable amount
  const remainingFunds = await incentive.getRemainingClaimPotential()

  await budget.clawbackFromTarget(
    core.assertValidAddress(),
    incentive.buildClawbackData(remainingFunds),
    boost.id,
    incentiveIndex
  );
}

Using clawbackFromTarget will modify the amount of the asset marked as distributed via the budget.

Parameters

address

required

The address of the contract implementing clawback, typically the Boost Core contract address.

Hex

required

The encoded clawback data payload. Generate this using incentive.buildClawbackData(amount).

bigint | number

required

The ID of the Boost containing the target incentive.

bigint | number

required

The index of the incentive to clawback from.

Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>

Returns

Promise<[amount, Address]>

Returns a tuple containing:

The amount that was successfully clawed back
The address of the token that was retrieved

Overview

Getting Started

Action Creation

Developers

SDK

API Guides

Retrieve from Budget

`clawback`

Parameters

Returns

`disburse`

Parameters

Returns

`disburseBatch`

Parameters

Returns

Retrieve from Incentive

`clawbackFromTarget`

Parameters

Returns

​Retrieve from Budget

​clawback

​Parameters

​Returns

​disburse

​Parameters

​Returns

​disburseBatch

​Parameters

​Returns

​Retrieve from Incentive

​clawbackFromTarget

​Parameters

​Returns

Retrieve from Budget

`clawback`

Parameters

Returns

`disburse`

Parameters

Returns

`disburseBatch`

Parameters

Returns

Retrieve from Incentive

`clawbackFromTarget`

Parameters

Returns