Pinning leases

sithbit mail pin keeps a message body available by re-pinning it to infrastructure you run. A pinning lease solves the same problem from the other side: it pays the recipient’s operator to keep their pin past the default retention window — the auto-settle sweeper normally releases a delivered copy’s pin about 30 days after delivery, and a live lease tells it not to.

A lease is a small on-chain account keyed on the message’s CID and your wallet. It escrows a reclaimable deposit (at least 0.01 SOL) and charges a one-time creation fee (default 0.001 SOL, split between the recipient’s mail operator and the postoffice). There is no expiry and no renewal: the pin stays protected exactly as long as the lease account exists, and closing it returns the deposit and the account rent in full. The fee is the only money spent.

sithbit mail lease create [to_address] [--message-id <id>] [--deposit <lamports>]
sithbit mail lease show   [to_address] [--message-id <id> | --cid <cid>] [--holder <address>]
sithbit mail lease close  [to_address] [--message-id <id> | --cid <cid>]

to_address defaults to your own address — leasing a message in your own mailbox — but any wallet may lease any message’s CID: a sender who wants their attachment to outlive the recipient’s retention window can lease it too. One lease exists per (CID, holder) pair, so your lease never collides with anyone else’s on the same message.

Creating a lease

sithbit mail lease create --message-id 3
sithbit mail lease create --message-id 3 --deposit 20000000

• --message-id (short -m) defaults to the latest message, matching mail pin.
• --deposit (short -d) defaults to the protocol minimum (PIN_LEASE_MIN_DEPOSIT_LAMPORTS, 0.01 SOL). The deposit rides on the lease account and comes back in full at close — the floor keeps a lease from being a near-free way to demand indefinite operator storage.
• The command quotes the current creation fee before sending (also readable anytime with sithbit postoffice fee pin-lease).

The lease must be created while the message account still exists on-chain — the program reads the CID off the message itself and verifies it cryptographically (the lease address derives from the CID’s hash, so a wrong CID simply cannot create the account). A message whose recipient opted out of IPFS carries a b3: local-only marker instead of a CID; there is no pinned body to retain, so leasing it is refused.

What the lease guarantees — and what it doesn’t

Operators running the stock sithbitd consult the chain before releasing a pin at settlement: a copy whose CID carries any live lease keeps its pin, and an operator that cannot prove the CID unleased (chain unreachable) keeps the pin too and retries later — the check fails safe. Settlement itself still happens: the recipient’s stamp value is still reclaimed on schedule; only the storage outlives it.

Two honest limits:

• A lease is an instruction to cooperating software, not a physical guarantee — an operator running modified software can drop any pin. For bodies you must keep regardless of the operator, mail pin to your own provider remains the trustless option (and composes with a lease).
• Closing a lease does not retroactively unpin a copy that already settled under it — the operator reclaims that storage through its own garbage collection, on its own schedule.

Inspecting and closing

sithbit mail lease show --cid QmTestCid
sithbit mail lease close --cid QmTestCid

show prints the holder, creation time, and escrowed deposit. close drains the account — deposit plus rent — back to the holder’s wallet; only the holder’s own signature can reach their lease (the account address derives from the holder, so there is nothing a stranger can even name). Both accept --message-id while the message record still exists; after the message settles and its on-chain record deallocates, pass --cid — the lease outlives the message on purpose.

The fee, for postmasters

The creation fee is a postoffice tunable with the standard shape: read it with sithbit postoffice fee pin-lease, tune it with sithbit postmaster fee pin-lease <LAMPORTS> (delegate-signed, capped at 10× the default; zero resets to the default rather than disabling the fee). Like every purchase-side fee it splits with the recipient’s registered domain authority at the tuned operator share — see the economics page.