Contract manager

[altafan]

To reach parity with the other sdks, we must introduce the contract manager, ie. the component that is in charge of creating scripts and addresses based on keys retrieved from the identity and contracts, that describe the script/address template, etc.

Ref: https://github.com/arkade-os/ts-sdk/tree/master/src/contracts.

[arkanaai]

Implementation already in place 🎉

The contract manager has been implemented at contract/. Here's what exists:

Files

File	Purpose
contract/manager.go	Manager interface + managerImpl (in-memory cache + write-through to store)
contract/types.go	Contract, Filter, Event, PathContext, PathSelection
contract/default_handler.go	DefaultHandler.DeriveContract — derives offchain ark address, P2TR boarding address, and bare key-path onchain address from a wallet key + server config
contract/handler.go	Keystore interface
contract/store.go	ContractStore persistence interface
init.go	Wires contract.NewManager on wallet unlock, tears it down on lock
funding.go	NewOffchainAddress, NewBoardingAddress, NewOnchainAddress — all delegate to contractManager.NewDefault()

What the default handler produces per key

• Contract.Address — Arkade bech32m offchain address (taproot tree: exit CSV leaf + forfeit multisig leaf)
• Contract.Boarding — P2TR boarding address (same tree, longer BoardingExitDelay)
• Contract.Onchain — bare key-path P2TR (no scripts)

---

Suggested acceptance criteria to close this issue

• contract.Manager interface defined with Load, NewDefault, GetContracts, GetContractsForVtxos, OnContractEvent, Close
• DefaultHandler.DeriveContract produces all three address facets from a wallet.KeyRef + clientTypes.Config
• DefaultHandler.SelectPath / GetSpendablePaths selects exit (CSV) or forfeit (multisig) leaf based on PathContext.Collaborative
• Manager bootstraps on Unlock, cleans up on Lock (init.go)
• ContractStore interface allows pluggable persistence (nil = in-memory only)
• funding.go public address methods delegate to the manager
• Integration/e2e test that exercises NewDefault → address derivation → spend path selection end-to-end (test files exist in contract/ but worth checking coverage against the ts-sdk reference)
• Any ts-sdk features not yet ported: contract expiry / ExpiresAt handling, contract_expired event emission, delta-sync with vtxo indexer

Potential gap vs ts-sdk

The ts-sdk reference (src/contracts/contractManager.ts) also handles VTXO delta-sync (reconciling pending frontier outputs from the indexer) and emits vtxo_received / vtxo_spent / contract_expired events. The Event type in types.go has Vtxos []clientTypes.Vtxo fields ready for this, but the manager doesn't currently emit those events — that wiring likely lives in sync.go. Worth confirming that's covered or tracking as a follow-up.