import type { RawTransactionRest, RawTransactionV2 } from '@did-btcr2/bitcoin';
import type { UnixTimestamp } from '@did-btcr2/common';
import type { DidServiceEndpoint, DidService } from '@web5/dids';

/**
 * Represents a Beacon Service, which extends a W3C DID Service by setting serviceEndpoint
 * as a single DidServiceEndpoint.
 * @interface BeaconService
 * @extends DidService
 */
export interface BeaconService extends DidService {
    serviceEndpoint: DidServiceEndpoint;
}

/**
 * Represents a parsed Beacon Service, which extends the Beacon Service with a Bitcoin address.
 * @interface ParsedBeaconService
 * @extends BeaconService
 */
export interface ParsedBeaconService extends BeaconService {
    /**
     * The Bitcoin address associated with this Beacon Service.
     */
    address: string;
}

/**
 * Metadata about a Bitcoin block containing a Beacon Signal.
 * @interface BlockMetadata
 */
export interface BlockMetadata {
   /**
   * The block height at which the Beacon Signal was included.
   */
  height: number;

  /**
   * The timestamp in the header of the block that contains the Beacon Signal.
   * The resolver compares it with `proof.created`.
   */
  time: UnixTimestamp;

  /**
   * The median time past of the block that contains the Beacon Signal: the
   * median of the header timestamps of that block and the ten blocks before it.
   * The value does not decrease from one block to the next, and no single miner
   * can change it. The resolver compares it with `ResolutionOptions.versionTime`
   * and `proof.expires`, and reports it as `updated` in the document metadata.
   */
  mediantime: UnixTimestamp;

  /**
   * The number of confirmations for the block containing the Beacon Signal.
   */
  confirmations: number;
}

/**
 * Represents a Beacon Signal, which is a transaction broadcasted by a Beacon to announce a DID update.
 * @interface BeaconSignal
 */
export interface BeaconSignal {
  /**
   * The raw Bitcoin transaction representing the Beacon Signal.
   */
  tx: RawTransactionRest | RawTransactionV2;

  /**
   * The beacon signal bytes hash (i.e. the hash of the BTCR2 update included in the Beacon Signal tx).
   */
  signalBytes: string;

  /**
   * Metadata about the block containing the Beacon Signal.
   */
  blockMetadata: BlockMetadata;
}

/**
 * Callback for publishing a CAS Announcement to a content-addressed store.
 * The method package defines this type; the caller provides the implementation
 * (e.g., the api layer's CasApi.publish backed by any CAS executor).
 *
 * Invoked before the beacon signal transaction is broadcast, so a thrown error
 * aborts the operation while the beacon UTXO is still unspent.
 *
 * @param announcement The CAS Announcement object (DID to update hash mapping).
 */
export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;