@arkade-os/sdk Documentation - v0.4.54
    Preparing search index...

    Interface IContractManager

    interface IContractManager {
        annotateVtxos(
            vtxos: VirtualCoin[],
        ): Promise<NormalizedExtendedVirtualCoin[]>;
        createContract(params: CreateContractParams): Promise<Contract>;
        deleteContract(script: string): Promise<void>;
        dispose(): void;
        getAllSpendingPaths(
            options: GetAllSpendingPathsOptions,
        ): Promise<PathSelection[]>;
        getContracts(filter?: ContractFilter): Promise<Contract[]>;
        getContractsWithVtxos(
            filter?: ContractFilter,
        ): Promise<ContractWithVtxos[]>;
        getSpendablePaths(
            options: GetSpendablePathsOptions,
        ): Promise<PathSelection[]>;
        getSyncState(): ContractSyncState;
        isWatching(): Promise<boolean>;
        onContractEvent(callback: ContractEventCallback): () => void;
        refillLookAhead(): Promise<void>;
        refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
        refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
        scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
        setContractState(script: string, state: ContractState): Promise<void>;
        updateContract(
            script: string,
            updates: Partial<Omit<Contract, "script" | "createdAt">>,
        ): Promise<Contract>;
    }

    Hierarchy

    • Disposable
      • IContractManager

    Implemented by

    Index

    Methods

    annotateVtxos createContract deleteContract dispose getAllSpendingPaths getContracts getContractsWithVtxos getSpendablePaths getSyncState isWatching onContractEvent refillLookAhead refreshOutpoints refreshVtxos scanContracts setContractState updateContract

    Methods

    • Stamp raw virtual outputs with the correct per-contract tapscripts (forfeit, intent, tap tree).

      Resolves each vtxo's script to its owning contract via the contract repository and attaches the matching tapscripts. Throws when any vtxo references a script with no registered contract — callers are expected to register the contract before asking for annotation. This is the single shared path that replaces scattered extendVirtualCoin* calls in wallet/handler code, and keeps the wallet from silently stamping the default tapscript onto a non-default vtxo.

      Parameters

      Returns Promise<NormalizedExtendedVirtualCoin[]>

    • Delete a contract by script and stop watching it. This — not retiring via setContractState — is the stop-watching path.

      Parameters

      • script: string

      Returns Promise<void>

    • Get all possible spending paths for a contract.

      Returns an empty array if the contract or its handler cannot be found.

      Parameters

      • options: GetAllSpendingPathsOptions

      Returns Promise<PathSelection[]>

    • List contracts with optional filters.

      Parameters

      • Optionalfilter: ContractFilter

      Returns Promise<Contract[]>

      const vhtlcs = await manager.getContracts({ type: "vhtlc" });
      const active = await manager.getContracts({ state: "active" });

    • Get all currently spendable paths for a contract.

      Returns an empty array if the contract or its handler cannot be found.

      Parameters

      • options: GetSpendablePathsOptions

      Returns Promise<PathSelection[]>

    • Rebuild the HD look-ahead watch window around the current allocation watermark. No-op when the manager was configured without lookAhead.

      Call after anything that moves the watermark (restore, boarding allocation, receive rotation, server-signer rotation). Concurrent calls coalesce into a single drain.

      Returns Promise<void>

    • Reconcile specific outpoints with the indexer's authoritative state and upsert the result into the wallet repository.

      The cursor-derived delta sync filters by created_at, so a VTXO that was created before the cursor but spent recently won't surface in a standard refreshVtxos() call. This method is the surgical recovery path for that case: when something hands us a stale outpoint (e.g. the server returns VTXO_ALREADY_SPENT with a vtxo_outpoint in its error metadata), call this to pull the latest state and unblock the caller — no full re-scan, no cursor change.

      Outpoints not owned by any tracked contract are silently dropped.

      Parameters

      Returns Promise<void>

    • Force a virtual output refresh from the indexer.

      Without options, refreshes all contracts from scratch. With options, narrows the refresh to specific scripts and/or a time window.

      Parameters

      • Optionalopts: RefreshVtxosOptions

      Returns Promise<void>

    • Explicit, gap-limit contract discovery used by wallet.restore().

      Walks HD indices from 0, asking every registered Discoverable handler whether it owns a contract anchored at that index, and registers each find via the idempotent createContract. A hit at index i (by any handler, including an injected swap handler) resets the gap counter, so swap discovery keeps the HD window open.

      Error contract (safety-critical — see spec §4):

      • A handler's discovery rejecting is collected into handlerErrors and makes its index indeterminate: it never advances the gap counter, and the scan stops verifying there rather than closing a window it never observed close. A batched Discoverable.discoverRange failure makes its whole requested range indeterminate. It still never throws.
      • A fatal operational error — materialize() throwing, or createContract rejecting — propagates out of scanContracts (it invalidates the gap-window signal, so a silent truncation would risk hiding user funds).

      Parameters

      Returns Promise<ScanResult>

      See ScanResult. The caller surfaces truncatedAt / handlerErrors after the inline VTXO pull.

    • Update mutable contract fields.

      script and createdAt are immutable.

      Parameters

      • script: string
      • updates: Partial<Omit<Contract, "script" | "createdAt">>

      Returns Promise<Contract>

    Settings

    Member Visibility

    On This Page

    Methods