Sponsored Tasks: Creating Sponsored Tasks

A manager funds a task from a vault by adding two flags to taskmarket task create. The task is created and paid for exactly as any other task; the flags add the Sponsored Task hook and its funding request.

Prerequisites

Your wallet is an active manager on the vault with enough remaining spend cap (Managing a vault).
The vault is active and has enough available tokens.
Your wallet has fee bank credit of at least one creation fee (Fees and the fee bank).
The vault's token decimals are known to Taskmarket (tokenDecimals is not null in taskmarket sponsored-task show <vaultId>).

Task creation itself does not need TASKMARKET_RPC_URL: it goes through the normal Taskmarket task-creation flow.

The command

taskmarket task create --description "..." --reward 5 --duration 24 \
  --sponsored-task <vaultId> --sponsored-task-tokens 100

Flag	Meaning
`--sponsored-task <vaultId>`	The vault to fund from.
`--sponsored-task-tokens <amount>`	Whole-token amount to reserve, for example `100` for 100 tokens.

Every other task create flag works as usual. --reward is still the USDC reward.

What the CLI does

Loads your keystore. Your wallet address is the manager address.
Fetches the vault and converts --sponsored-task-tokens to base units with the vault's token decimals.
Calls the funding preview (GET /api/sponsored-task-vaults/<vaultId>/preview-funding), which reads the live chain state. If any check fails, the CLI stops before asking for payment and prints Sponsored task funding would fail: followed by the failure codes.
Asks the backend to build the funding request (POST /api/sponsored-task-vaults/<vaultId>/build-funding-hook-data). The backend reads the vault's live epoch and fee terms and computes the task terms hash from the task's mode, deadlines, reward, evaluator settings and hooks.
Appends the Sponsored Task hook address to the task's hooks and sends the encoded funding request as the task's hookData.

Funding preview failures

The preview returns { "ok": boolean, "failures": [...] }. Every check runs, so several codes can come back together.

Code	Meaning	Fix
`HOOK_NOT_CONFIGURED`	The Taskmarket backend has no Sponsored Task hook configured for this network.	None on your side; Sponsored Tasks are not available on that backend.
`VAULT_NOT_ACTIVE`	The vault has been exited.	Use another vault. An exited vault cannot be reactivated.
`MANAGER_NOT_ACTIVE`	Your wallet is not an active manager on the vault.	Ask the owner to run `managers add` for your address.
`MANAGER_CAP_EXCEEDED`	The amount exceeds your remaining spend cap (`cap - reserved - spent`).	Reserve less, or ask the owner to raise your cap.
`VAULT_INSOLVENT`	The vault's token balance is below what it owes, so `available()` reverts.	Contact the vault owner. This happens with balance-mutating tokens.
`VAULT_INSUFFICIENT_AVAILABLE`	The vault's available balance is below the amount.	Reserve less, or ask the owner to fund the vault.
`HOOK_NOT_AUTHORIZED_CHARGER`	The fee bank does not authorize the hook to charge credit.	None on your side; sponsored task creation is disabled on that deployment.
`INSUFFICIENT_FEE_CREDIT`	Your fee bank credit is below the current creation fee.	Run `taskmarket sponsored-task fee-bank deposit`.

Flag rules

The CLI stops with these messages before contacting the chain:

Situation	Message
Only one of the two flags given	`--sponsored-task and --sponsored-task-tokens must be used together`
Zero tokens	`--sponsored-task-tokens must be greater than zero`
Combined with `--hook-data`	`--hook-data cannot be combined with --sponsored-task -- the sponsored task funding request is the hookData`
Vault token decimals unknown	`This vault has no known token decimals -- its ERC-20 could not be read. Contact the vault owner.`
More than 8 hooks in total	`--hook accepts at most 8 custom addresses; current protocol defaults count toward the on-chain maximum of 8`

A task has a single hookData slot, and a sponsored task uses it for the funding request, which is why --hook-data is rejected. Other --hook addresses can still be attached; the Sponsored Task hook counts toward the limit of 8.

Supported task modes

The funding request accepts every task mode: bounty, claim, pitch, benchmark and auction (with any auction type). The CLI always builds the request with no worker stake, so sponsored tasks are created without a stake requirement.

On-chain checks at creation

Even after a clean preview, the hook re-checks everything inside the task-creation transaction, and any failure reverts the whole creation, fee charge included:

The task pays in USDC and the requester is the manager named in the funding request.
The funding request's terms hash matches the task's current terms (TaskTermsMismatch).
The vault is registered in the registry, active, on this chain, at the stated epoch, and controlled by this hook (VaultMismatch).
The task has no existing sponsored allocation (AllocationAlreadyExists); a task carries at most one sponsored allocation.
The fee bank charge succeeds (InsufficientCredit).
The vault reservation succeeds: ManagerNotActive, ManagerAllowanceExceeded, InsufficientAvailable, Insolvent, AllocationEpochMismatch or FeeTermsMismatch.

A state change between the preview and the transaction, such as the owner withdrawing tokens or the fee terms changing, is the usual reason for a revert after a clean preview.

After creation

The task's sponsoredTaskRewards entry starts as reserved. From there the lifecycle is automatic; see How it works. Accept, reject and evaluate the task exactly as you would any other; the sponsored reward follows the verdict.

Contents