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

Transfer an alias

See Aliases for what an alias is and why a transfer is always a two-party consent ceremony rather than a unilateral push. This page covers the sithbit alias transfer command tree.

sithbit alias transfer init <alias> <recipient> \
  [--fee <lamports>] [--expires-in <seconds>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Offers to move an existing alias to a new wallet address. Every transfer is a two-party ceremony: the alias’s current holder signs to stage the offer, and the alias changes hands only when the named recipient signs to accept it. Both consents are structural — an alias can never be taken from its owner without their key, and it can never be planted on a wallet that didn’t ask for it.

--fee is the price, in lamports, the recipient pays the holder on acceptance. It defaults to 0 — a free hand-off:

sithbit alias transfer init john_doe maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR

The alias keeps resolving to the current holder until the recipient runs alias transfer accept. A free hand-off pays the flat alias-transfer fee to the postoffice at accept — waived when the offer’s holder is the standing delegate, so operator reservation hand-offs stay fee-free — while a priced offer pays the 90/10 split instead (see Economics).

See Closing accounts for how to close an alias instead of transferring it.

The consent guarantee. Before v0.7.0 the TransferAlias instruction repointed an alias at any address with only the holder’s signature — a name could be attached to a wallet unilaterally. That instruction now refuses with custom error 85 (UnilateralTransferDisabled); its discriminant remains decodable so pre-cutover history replays cleanly. See the change history.

Selling an alias: escrowed transfer for a fee

With a positive --fee, the same command stages the offer as a sale: the alias changes hands only when the named recipient accepts the offer and pays the fee. Until then the alias keeps resolving to the current holder, exactly as before.

sithbit alias transfer init john_doe <RECIPIENT_PUBKEY> --fee 50000000

The offer names one specific recipient — only that wallet can accept it — and each alias can carry at most one outstanding offer (the offer lives in a dedicated escrow account derived from the alias name, so a second simultaneous offer is structurally impossible). The holder fronts the escrow account’s rent when staging the offer and gets it back when the offer resolves, whichever way it resolves.

The binding window

For its first 5 minutes an offer is binding on the holder: it can be neither cancelled nor replaced. This protects a recipient who sees the offer and pays promptly from having it retracted out from under them mid-purchase.

Replacing an offer

To change the fee, the recipient, or the expiry, just issue a new alias transfer init for the same alias — a new offer replaces the standing one in place (no cancel-first needed, and no extra rent). The replacement re-arms the 5-minute binding window.

Expiry

An offer expires 30 days after it is staged, unless you pass a different lifetime in seconds:

sithbit alias transfer init john_doe <RECIPIENT_PUBKEY> --fee 50000000 --expires-in 86400

Enforcement is lazy — nothing sweeps expired offers. An accept at or before the expiry instant succeeds; an accept after it is refused. The escrow account of an expired offer sits until the holder cancels it (see below) or stages a replacement.

Accepting an offer

sithbit alias transfer accept <alias> \
  [--payer-keypair <keypair>] \
  [--keypair <keypair>] \
  [--skip-preflight]

The offer’s named recipient signs — the signature is the consent, so an alias can never be planted on a wallet that didn’t ask for it. In one atomic instruction the fee leg settles, the alias repoints at the recipient, and the escrow closes with its rent refunded to the previous holder. The fee leg depends on the offer’s price:

  • Priced offer — the fee leaves the paying wallet and splits between the current holder and the postoffice (90/10 — see Economics for the exact money flow). No flat fee rides on top.
  • Free hand-off (fee 0) — the paying wallet pays the flat alias-transfer fee (default 0.001 SOL, postmaster-tunable) to the postoffice, waived when the offer’s holder is the standing delegate. The CLI prints the fee (or the waiver) before signing.
sithbit alias transfer accept john_doe -k recipient.json

By default the recipient’s own wallet pays. A sponsor may pay instead with --payer-keypair — the sponsor funds the fee and the transaction fee and co-signs alongside the recipient. (Simply funding the recipient’s wallet beforehand works too.)

Cancelling an offer

sithbit alias transfer cancel <alias> [--keypair <keypair>] [--skip-preflight]

The holder cancels an outstanding offer (once its binding window has elapsed), closing the escrow and reclaiming its rent:

sithbit alias transfer cancel john_doe

This is also how you reclaim the escrow rent of an expired offer — an expired offer can no longer be accepted, but its account stays open until the holder cancels it.

While an offer is pending

  • The alias resolves to the current holder until the moment the offer is accepted; mail keeps working unchanged.
  • sithbit alias close refuses while a transfer offer is outstanding — cancel the offer first, then close (otherwise the escrow’s rent would be stranded).