Contract watcher

[altafan]

The current logic for watching internal addresses (owned by the client), now lives in the client.
To reach parity with other sdks we can move it to a watcher component that lives in the contract manager and that could be reused by consumers of the sdk.

[arkanaai]

Codebase Context

The watching logic lives in two places:

client.go

• listenForOnchainTxs() (~L800–1117) — subscribes to explorer address events for boarding, onchain, and offchain-equivalent addresses. When a new contract is created, it dynamically subscribes via contractManager.OnContractEvent().
• listenForArkTxs() (~L717–798) — streams offchain Ark transactions and filters them by matching pubkeys from contracts.

Both functions are methods on the top-level client struct and run as background goroutines spawned in init.go (Unlock()).

contract/manager.go — ContractManager already exists and handles contract lifecycle, storage, and event callbacks (OnContractEvent). It's a natural home for a watcher subcomponent.

contract/types.go — Contract holds the three address types: Address (offchain), Boarding, Onchain.

broadcaster.go — generic broadcaster used by the client to fan out UTXO/VTXO/TX events to subscribers.

---

Suggested Acceptance Criteria

• A Watcher type (or interface + impl) lives under contract/ and is owned/instantiated by the contract manager
• The watcher encapsulates address subscription logic currently in listenForOnchainTxs: subscribing boarding, onchain, and offchain-equivalent addresses to the explorer, and handling contract_created events to subscribe new addresses dynamically
• The watcher handles reconnect/resubscribe on explorer disconnect (parity with other SDKs)
• client.go delegates to contract.Watcher instead of owning the subscription loop directly — listenForOnchainTxs either moves or becomes a thin wrapper
• Ark transaction filtering (listenForArkTxs) is either also moved or clearly out of scope with a follow-up noted
• Existing UTXO/VTXO event broadcasting behaviour is preserved (no regression)
• Unit tests for the watcher component covering: initial address subscription on load, dynamic subscription on new contract, and reconnect behaviour

---

Potential Approach

1. Create contract/watcher.go with a Watcher struct that takes an Explorer, ContractStore, and network config.
2. Watcher.Start(ctx) — loads all contracts, subscribes addresses, calls explorer.GetAddressesEvents() in a loop.
3. Watcher subscribes to manager.OnContractEvent to catch new contracts at runtime.
4. Watcher emits UTXO events via a channel or callback — keeping the broadcaster fan-out in the client, or moving it too if the goal is full extraction.
5. ContractManager constructs and owns the Watcher; init.go just calls manager.StartWatcher(ctx).

The main complexity is threading the UTXO event callbacks back up to the broadcaster without creating a circular dependency between contract/ and the top-level client.

[bitcoin-coder-bob]

working off PR: #153