VHTLC contract

[altafan]

Let's add support for VHTLC contract.

Ref: https://github.com/arkade-os/ts-sdk/blob/master/src/contracts/handlers/vhtlc.ts

[arkanaai]

Context

This adds a new contract handler to the contract/ package, mirroring the TypeScript reference at ts-sdk/src/contracts/handlers/vhtlc.ts.

Relevant files:

• contract/default_handler.go — the pattern to follow (implement Handler interface)
• contract/types.go — Contract, PathContext, PathSelection types (already has Preimage []byte field in PathContext)
• contract/manager.go — where the new handler needs to be registered
• arkd/pkg/ark-lib/script/closure.go — all 6 required closure types already exist

The good news: all the Bitcoin script primitives needed are already implemented in arkd's closure package.

---

Acceptance Criteria

• contract/vhtlc_handler.go implementing the Handler interface with:
  • VHTLCParams struct (sender, receiver, server pubkeys; preimageHash [20]byte; refundLocktime uint32; unilateralClaimDelay, unilateralRefundDelay, unilateralRefundWithoutReceiverDelay RelativeLocktime)
  • DeriveContract — builds the 6-leaf taproot tree, derives Ark address (no boarding address for VHTLC — this is a payment contract, not a wallet contract)
  • SelectPath — role-aware (sender/receiver via PathContext.WalletPubKey), respects CLTV (PathContext.BlockHeight) and CSV timing
  • GetSpendablePaths — returns all currently spendable leaves, with preimage in ExtraWitness[0] for claim paths
  • Params serialized to/from map[string]string (hex pubkeys, decimal integers)
• contract/vhtlc_handler_test.go covering path selection for both roles, with/without preimage, before/after timelocks
• Handler registered in contract/manager.go
• const TypeVHTLC = "vhtlc" constant exported

---

Approach

Script leaves (fixed index order, matching ts-sdk):

[0] claim                          — ConditionMultisigClosure{pubkeys:[receiver,server], condition:OP_HASH160 <hash> OP_EQUAL}
[1] refund                         — MultisigClosure{pubkeys:[sender,receiver,server]}
[2] refundWithoutReceiver          — CLTVMultisigClosure{pubkeys:[sender,server], locktime:refundLocktime}
[3] unilateralClaim                — ConditionCSVMultisigClosure{pubkeys:[receiver], condition:hash160, delay:claimDelay}
[4] unilateralRefund               — CSVMultisigClosure{pubkeys:[sender,receiver], delay:refundDelay}
[5] unilateralRefundWithoutReceiver — CSVMultisigClosure{pubkeys:[sender], delay:refundNoReceiverDelay}

Path selection logic (matches ts-sdk exactly):

• Determine role: match PathContext.WalletPubKey against sender/receiver params
• Collaborative + receiver + preimage → leaf[0], ExtraWitness: [preimage]
• Collaborative + sender + CLTV satisfied → leaf[2]
• Unilateral + receiver + preimage + CSV ready → leaf[3], ExtraWitness: [preimage], Sequence set
• Unilateral + sender + CSV ready → leaf[5], Sequence set

Note: PathContext.Preimage is already wired in types.go — no type changes needed.

⚠️ This touches VTXO spending paths — flag for human review before merge.

[tiero]

Do we really need a bespoke contract type for it?

I guess we could just treat it as we would treat the other custom script contracts, and ideally we expose this as template, but since go doesnt really have a concept of class/inheritance I would just have a file with the opcodes to encode to a script, like we do in this "example"

for spending we can always have a dedicated pkg that knows how to craft the custom transactions (claim, refunds), in meantime we progress with the compiler work so we could statically generate these custom tx building, starting from a contract template

wdyt?

[bitcoin-coder-bob]

working off PR: #157