Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Set a domain’s sponsor policy

See Sponsored mailboxes for what a sponsored mailbox is and Domains for who sets the policy. This page covers the sithbit domain sponsor-policy command.

sithbit domain sponsor-policy <domain> \
  [--cap <count>] \
  [--rate <count>] \
  [--delegate <address>] \
  [--keypair <authority keypair>] \
  [--skip-preflight] \
  [--tx-version <legacy|v1>]

The command overwrites the cap, the rate and the delegate on the domain’s account in one transaction: how many sponsored mailboxes the domain may hold unclaimed at once, how many it may create per cluster epoch, and which key may sponsor beside the authority. It requires the CLI’s domain feature, which is enabled by default.

Who signs

The domain’s current authority signs (--keypair, defaulting to the CLI’s configured keypair) — the same role that signs domain sell. Neither the delegate nor the sponsor delegate this command names may set the policy: a signer that is not the domain’s authority is refused with IllegalAuthority. The instruction does not consult the domain’s active flag, so an inactive domain’s policy stays settable.

Arguments

  • <domain> (required) — the domain whose policy to set (case-insensitive).
  • --cap <count> (optional) — the most sponsored mailboxes the domain may hold unclaimed at once. Defaults to 0, which means unlimited.
  • --rate <count> (optional) — the most sponsored mailboxes the domain may create per cluster epoch. Defaults to 0, which means unlimited.
  • --delegate <address> (optional) — a key that may pay for sponsored mailboxes beside the authority. Omitted, the domain has no sponsor delegate.
  • --keypair <authority keypair> (optional, -k) — the domain authority’s signing keypair; also pays the transaction fee.
  • --skip-preflight (optional) — submits the transaction without a local simulation pass first.
  • --tx-version <legacy|v1> (optional) — the transaction format, described once under Choosing the transaction version.

The command replaces the whole policy: an omitted --cap, --rate or --delegate resets that setting to unlimited, unlimited or none, so to change only the cap, pass the rate and delegate you want to keep as well. domain get prints the current policy.

What the policy enforces

A sponsored mailbox create --for is accepted only from the domain’s authority or its sponsor delegate. A domain’s sponsor counter then refuses a create once the domain holds --cap mailboxes the owners have not yet activated (SponsorCapExceeded, error 110) and once it has made --rate sponsored creates in the current epoch (SponsorRateExceeded, error 111). An owner’s first update or close request activates a sponsored mailbox and releases it from the cap count; the funder’s mailbox reclaim-dormant releases it too. The program reference documents the counter’s reset on an authority change and the one-second boundary case it accepts.

When the authority changes

The cap and rate belong to the domain and survive a change of authority; the sponsor delegate does not. TransferDomainAuthority, BuyDomain and FinalizeReclaimByProof each clear the delegate to none, because the outgoing holder chose it. The new authority runs domain sponsor-policy again to name its own.

Example

Set a cap of 500 unclaimed sponsored mailboxes and a rate of 25 per epoch, sponsored by a hot key while the authority key stays cold:

sithbit domain sponsor-policy sithbit.com --cap 500 --rate 25 \
  --delegate maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR \
  --keypair <path to authority keypair>
Domain 'sithbit.com' sponsorship policy set
https://explorer.solana.com/tx/…

Remove every limit and the delegate:

sithbit domain sponsor-policy sithbit.com

See also