Timelock Awareness and Native Support for Attached UTXOs

[StampBlaster5000]

Status: Draft
Created: 2026-03-17
References: PSBT Support via attaching assets to UTXOs

Motivation: Counterparty’s UTXO attachment + PSBT atomic swaps unlocked real marketplace trading. Timelocks now let us add powerful safety and new patterns:

• Listing safety lock — Bind asset to UTXO + 7-day timelock when listing. Users can freely move BTC in/out of their wallet; the listed asset is cryptographically unspendable (prevents accidental sweeps, bugs, or malware). When ready to delist, just wait for expiry or cancel.
• Delayed-release sales / auctions (e.g. “3-day lock after listing”)
• Vault-style escrow
• Inheritance / dead-man-switch assets (owner pings every 6–12 months; heirs claim after timeout)

Without protocol awareness, timelocked listings create failed PSBT orders and confusion. Bitcoin enforces the timelock, but Counterparty’s indexer, API, and compose endpoints have zero awareness of CLTV, CSV, or nLockTime. The result is broken PSBT orders and no protocol-level visibility. We can fix this with minimal, backward-compatible changes — Bitcoin still does all the enforcement. This CIP makes them first-class and visible, empowering utxo bound assets with Bitcoin's Trustless vaults.

Proposed Changes
(indexer stores timelock data, API exposes it, new attach_with_timelock compose endpoint, optional new message)

Indexer / Database
When processing ATTACH_TO_UTXO (or the new message below), parse:

• Output scriptPubKey for OP_CLTV / OP_CSV
• Transaction nLockTime and input nSequence
  Store in utxos table.

API Extensions (fully backward-compatible)
/v2/utxos/ and balance endpoints add:

Optional New Protocol Message

• ATTACH_WITH_TIMELOCK (one new message type, same XCP fee model).
• Uses standard Bitcoin templates (P2WSH + CLTV/CSV or Miniscript). Existing ATTACH_TO_UTXO stays unchanged.

Advanced: HTLC Support (optional extension, zero extra cost)
HTLCs (Hashed Timelock Contracts) combine a hashlock (reveal secret preimage) + timelock (CLTV or CSV). They enable conditional atomic trades, escrows, and cross-chain swaps directly on attached Counterparty assets.

If the indexer already parses CLTV/CSV for pure timelocks, HTLC detection comes for free (just look for the common sha256(...) + timelock branch pattern). Marketplaces can then show:

Wallet & Marketplace Behaviour

• Counterparty supported wallets, marketplaces, and explorers automatically show countdown + “Locked until…” warning.
• Buy buttons / PSBT generation disabled until expiry (or show clear warning).
• Existing non-timelocked UTXOs are unaffected (timelock: null).

Benefits

• Zero-trust, 100% on-chain protection (Bitcoin enforces the lock).
• Prevents accidental spending of listed assets while allowing normal BTC wallet use.
• Seamless PSBT marketplace integration with countdowns and warnings. — just one extra API field.
• New use-cases (auctions, vaults, inheritance) without any Bitcoin changes
• Tiny implementation cost (script parsing already exists in counterparty-lib)

Implementation Notes

• No consensus change required.
• Test vectors will be provided (e.g. attach to 100-block CSV → API shows locked → spend after 100 blocks → normal UTXO_MOVE).
• Backward compatible: old nodes/indexers ignore new fields.

[adamkrellenstein]

Oooh good idea!