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: 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.

Contents

Prerequisites

  • Your wallet is an active manager on the vault with enough remaining spend cap (Managing a vault). taskmarket sponsored-task managed lists the vaults you can fund from, with your remaining cap (CLI reference).
  • 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
FlagMeaning
--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

  1. Loads your keystore. Your wallet address is the manager address.
  2. Fetches the vault and converts --sponsored-task-tokens to base units with the vault's token decimals.
  3. 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.
  4. 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.
  5. Appends the Sponsored Task hook address to the task's hooks and sends the encoded funding request as the task's hookData.

In the web app

The task-create form at /dashboard/tasks/new runs the same steps. On the review step, with a wallet connected, the Sponsored reward (optional) section:

  1. Lists the active vaults where the connected wallet is an active manager, with each vault's token, curation status (approved or unverified), your remaining spend cap and the vault's available balance. If the wallet manages none, the section says so and nothing is attached.
  2. Takes a whole-token amount and converts it with the vault's token decimals. A vault with unknown decimals cannot be used.
  3. Runs the funding preview as you type and shows a message for each failure code. For INSUFFICIENT_FEE_CREDIT it links to the fee bank card on the vault page.
  4. Adds a Sponsored reward (from vault) line to the cost breakdown once the preview passes.
  5. On Fund and publish, builds the funding request from the same task fields that are being published, appends the Sponsored Task hook after any custom hooks, and sends the funding request as hookData.

Publishing is blocked while a vault is chosen but the amount is missing or the preview has not passed; choose No sponsored reward to publish without one. If the task already has custom hook data, the section explains the conflict and links back to the details step instead of offering a vault. Unlike the CLI, the web form builds the funding request with the task's actual stake settings.

The vault and amount are saved with the task draft in this browser tab, so they survive a reload. On restore the form runs the funding preview again. If the saved vault is no longer an active vault that the connected wallet manages, the form clears the sponsored reward and says so. Drafts are web-only; the CLI has no draft state, so task create takes both flags on every run.

Funding preview failures

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

CodeMeaningFix
HOOK_NOT_CONFIGUREDThe 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_ACTIVEThe vault has been exited.Use another vault. An exited vault cannot be reactivated.
MANAGER_NOT_ACTIVEYour wallet is not an active manager on the vault.Ask the owner to run managers add for your address.
MANAGER_CAP_EXCEEDEDThe amount exceeds your remaining spend cap (cap - reserved - spent).Reserve less, or ask the owner to raise your cap.
VAULT_INSOLVENTThe vault's token balance is below what it owes, so available() reverts.Contact the vault owner. This happens with balance-mutating tokens.
VAULT_INSUFFICIENT_AVAILABLEThe vault's available balance is below the amount.Reserve less, or ask the owner to fund the vault.
HOOK_NOT_AUTHORIZED_CHARGERThe fee bank does not authorize the hook to charge credit.None on your side; sponsored task creation is disabled on that deployment.
INSUFFICIENT_FEE_CREDITYour 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:

SituationMessage
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 unknownThis 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). For a claim task, --stake-required and --stake-bps are sent in the funding request as well as the task, so the terms the vault signs match the task that is created. Without them, the task has no 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.