Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Sponsored Tasks: Overview

Sponsored Tasks let a project attach its own ERC-20 token to a Taskmarket task as a second reward, next to the ordinary USDC reward every task carries. The project deposits its token into a vault, authorizes one or more managers to spend from it, and each manager creates tasks that reserve tokens from the vault. When the task's verdict lands, the reserved tokens are split across the same winners the USDC payout goes to, and each winner claims their share.

Contents

Who Sponsored Tasks are for

RoleWhat they doStart here
Sponsor (vault owner)Creates a vault for a project token, funds it, authorizes managers, withdraws unreserved tokens, and can terminally exit the vault.Setting up a vault, Managing a vault
ManagerHolds a spend cap on a vault and USDC fee credit in the fee bank, and creates tasks funded from the vault. A manager may be the owner's own address.Creating sponsored tasks, Fees and the fee bank
WorkerCompletes the task as usual and, if they win, claims the project-token reward gaslessly to their withdrawal address.Claiming rewards
IntegratorReads vaults and rewards through the public API.API reference

The USDC reward is unchanged by any of this. It settles through Taskmarket's own protocol path whether or not the task is sponsored, and whatever happens to the vault.

How a sponsored reward looks on a task

A task's list and detail responses carry an optional sponsoredTaskRewards array. The field is omitted entirely when the task has no sponsored reward. Each entry looks like this:

{
  "vaultId": "0x...",
  "tokenAddress": "0x...",
  "tokenSymbol": "EXAMPLE",
  "tokenDecimals": 18,
  "grossAmount": "100000000000000000000",
  "feeAmount": "7500000000000000000",
  "netAmount": "92500000000000000000",
  "feeBps": 750,
  "state": "reserved",
  "curationStatus": "approved"
}
FieldMeaning
vaultIdThe vault the reward is reserved from (bytes32).
tokenAddress, tokenSymbol, tokenDecimalsThe project token. Symbol and decimals are read from the token and can be null if it does not expose them.
grossAmountTokens reserved from the vault, in base units.
feeAmount, netAmountThe token fee and the worker-facing remainder, in base units. Either can be null.
feeBpsThe token fee rate snapshotted when the task was reserved (750 is 7.5%).
statereserved, credited, released, defaulted or award_count_exceeded. See How it works.
curationStatusunverified, approved or rejected. See Curation.

The token amount a worker earns is not proportional to the USDC award in any simple way. Read the reward's own amounts off the task; see How it works.

Glossary

TermMeaning
VaultA SponsoredTasksVault: a one-token contract holding a project's tokens. Each vault is an immutable minimal clone deployed by the factory and owned by the sponsor.
vaultIdThe vault's bytes32 identifier, keccak256(chainId, factory, vault). CLI read commands, task create --sponsored-task and the API take the vaultId; on-chain administration commands take the vault address.
OwnerThe vault's owner. Only the owner can configure managers, withdraw unreserved tokens, or exit. Ownership transfers in two steps and cannot be renounced.
ManagerAn address the owner authorizes to reserve tokens from the vault when it creates a task. The manager must be the task's requester.
Spend capA manager's lifetime token allowance on one vault, in base units. Reserved plus already-spent tokens count against it; the owner raises it to grant more.
CuratorA Taskmarket reviewer who sets a vault's off-chain curationStatus. Curation changes how Taskmarket presents a vault, never what the chain allows.
Fee bankThe SponsoredTaskFeeBank contract that holds each manager's USDC fee credit and charges one creation fee per sponsored task.
GuardThe SponsoredTaskFeeBankGuard contract that owns the fee bank and limits what its administrator can do, including a fixed ceiling on the creation fee.
ReservationTokens set aside in the vault for one task at creation. Reserved tokens cannot be withdrawn by the owner while the vault is active.
SettlementThe step after a verdict that turns a reservation into per-winner entitlements (a Merkle root installed in the vault) and returns any undistributed tokens to the vault's available balance.
KeeperA Taskmarket backend job that drives finished tasks' reservations to settled or released.
EpochA counter on the vault. It starts at 1 and advances when the owner exits the vault, which invalidates every reservation, entitlement and claim signature from the earlier epoch.
EntitlementOne winner's claimable share of a settled task: a Merkle leaf naming the worker and net token amount.

Where to go next