Payloads

Entidad de la carga útil de escrow

import { EscrowType, SingleReleaseEscrowStatus } from "./types";
import { MultiReleaseEscrow, Role, SingleReleaseEscrow } from "./types.entity";

/**
 * Documentación: https://docs.trustlesswork.com/trustless-work/developer-resources/quickstart/integration-demo-project/entities
 */

// ----------------- Cargas útiles de hitos -----------------
/**
 * Carga útil de Hito de Liberación Única
 */
export type SingleReleaseMilestonePayload = {
  /**
   * Texto que describe la función del hito
   */
  description: string;
};

/**
 * Carga útil de Hito de Múltiples Liberaciones
 */
export type MultiReleaseMilestonePayload = {
  /**
   * Texto que describe la función del hito
   */
  description: string;
  /**
   * Cantidad a transferir al completarse este hito
   */
  amount: number;
  /**
   * Dirección a la que se enviarán los ingresos del hito
   */
  receiver: string;
};

// ----------------- Inicializar escrow -----------------
/**
 * Carga útil para inicializar escrow de liberación única
 */
export type InitializeSingleReleaseEscrowPayload = Omit<
  SingleReleaseEscrow,
  "contractId" | "balance" | "milestones"
> & {
  /**
   * Objetivos que deben completarse para definir el escrow como completado
   */
  milestones: SingleReleaseMilestonePayload[];
};

/**
 * Carga útil para inicializar escrow de múltiples liberaciones
 */
export type InitializeMultiReleaseEscrowPayload = Omit<
  MultiReleaseEscrow,
  "contractId" | "balance" | "milestones"
> & {
  /**
   * Objetivos que deben completarse para definir el escrow como completado
   */
  milestones: MultiReleaseMilestonePayload[];
};

// ----------------- Actualizar escrow -----------------
/**
 * Carga útil para actualizar escrow de liberación única
 */
export type UpdateSingleReleaseEscrowPayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Datos del escrow
   */
  escrow: Omit<SingleReleaseEscrow, "contractId" | "signer" | "balance"> & {
    /**
     * Si el escrow está activo. Esto proviene de la BD, no de la blockchain.
     */
    isActive?: boolean;
  };

  /**
   * Dirección del usuario que firma la transacción del contrato
   */
  signer: string;
};

/**
 * Carga útil para actualizar escrow de múltiples liberaciones
 */
export type UpdateMultiReleaseEscrowPayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Datos del escrow
   */
  escrow: Omit<MultiReleaseEscrow, "contractId" | "signer" | "balance"> & {
    /**
     * Si el escrow está activo. Esto proviene de la BD, no de la blockchain.
     */
    isActive?: boolean;
  };

  /**
   * Dirección del usuario que firma la transacción del contrato
   */
  signer: string;
};

// ----------------- Cambiar estado del hito -----------------
/**
 * Carga útil para cambiar el estado del hito, puede ser de liberación única o múltiple
 */
export type ChangeMilestoneStatusPayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Índice del hito que se va a actualizar
   */
  milestoneIndex: string;

  /**
   * Nuevo estado del hito
   */
  newStatus: string;

  /**
   * Nueva evidencia del trabajo realizado por el proveedor del servicio.
   */
  newEvidence?: string;

  /**
   * Dirección de la entidad que presta el servicio.
   */
  serviceProvider: string;
};

// ----------------- Aprobar hito -----------------
/**
 * Carga útil para aprobar el hito, puede ser de liberación única o múltiple
 */
export type ApproveMilestonePayload = Omit<
  ChangeMilestoneStatusPayload,
  "serviceProvider" | "newStatus"
> & {
  /**
   * Dirección de la entidad que solicita el servicio.
   */
  approver: string;
};

// ----------------- Iniciar disputa -----------------
/**
 * Carga útil para iniciar disputa en liberación única. Esto inicia una disputa para todo el escrow.
 */
export type SingleReleaseStartDisputePayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Dirección del usuario que firma la transacción del contrato
   */
  signer: string;
};

/**
 * Carga útil para iniciar disputa en múltiples liberaciones. Esto inicia una disputa para un hito específico.
 */
export type MultiReleaseStartDisputePayload =
  SingleReleaseStartDisputePayload & {
    /**
     * Índice del hito que se disputará
     */
    milestoneIndex: string;
  };

// ----------------- Resolver disputa -----------------
/**
 * Carga útil para resolver disputa
 */
export type SingleReleaseResolveDisputePayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Dirección encargada de resolver disputas dentro del escrow.
   */
  disputeResolver: string;

  /**
   * Distribuciones del monto del escrow a los receptores.
   */
  distributions: [
    {
      /**
       * Dirección del receptor
       */
      address: string;
      /**
       * Cantidad que se transferirá al receptor. Toda la cantidad debe ser igual al monto total del escrow.
       */
      amount: number;
    },
  ];
};

/**
 * Carga útil para resolver disputa en múltiples liberaciones
 */
export type MultiReleaseResolveDisputePayload =
  SingleReleaseResolveDisputePayload & {
    /**
     * Índice del hito que se resolverá
     */
    milestoneIndex: string;
  };

// ----------------- Retirar fondos restantes -----------------
/**
 * Retirar fondos restantes
 */
export type WithdrawRemainingFundsPayload = SingleReleaseResolveDisputePayload;

// ----------------- Financiar escrow -----------------
/**
 * Carga útil para financiar escrow, puede ser de liberación única o múltiple
 */
export type FundEscrowPayload = {
  /**
   * Cantidad a transferir al completarse los hitos del escrow
   */
  amount: number;

  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Dirección del usuario que firma la transacción del contrato
   */
  signer: string;
};

// ----------------- Obtener escrows desde el indexador -----------------
/**
 * Parámetros para obtener escrows desde el indexador
 */
export type GetEscrowsFromIndexerParams = {
  /**
   * Número de página. Paginación
   */
  page?: number;

  /**
   * Dirección de ordenamiento. Ordenamiento
   */
  orderDirection?: "asc" | "desc";

  /**
   * Ordenar por propiedad. Ordenamiento
   */
  orderBy?: "createdAt" | "updatedAt" | "amount";

  /**
   * Creado en = fecha de inicio. Filtrado
   */
  startDate?: string;

  /**
   * Creado en = fecha de fin. Filtrado
   */
  endDate?: string;

  /**
   * Monto máximo. Filtrado
   */
  maxAmount?: number;

  /**
   * Monto mínimo. Filtrado
   */
  minAmount?: number;

  /**
   * Está activo. Filtrado
   */
  isActive?: boolean;

  /**
   * Escrow que estás buscando. Filtrado
   */
  title?: string;

  /**
   * ID de compromiso. Filtrado
   */
  engagementId?: string;

  /**
   * Estado del escrow de liberación única. Filtrado
   */
  status?: SingleReleaseEscrowStatus;

  /**
   * Tipo de escrow. Filtrado
   */
  type?: EscrowType;

  /**
   * Si es true, los escrows se validarán en la blockchain para garantizar la consistencia de los datos.
   * Esto realiza un paso adicional de verificación para confirmar que los datos del escrow
   * devueltos por el indexador coinciden con el estado actual en la blockchain.
   * Usa esto cuando necesites asegurar la información de escrow más actualizada y precisa.
   * Si activas este parámetro, tu solicitud tardará más en completarse.
   */
  validateOnChain?: boolean;
};

export type GetEscrowsFromIndexerBySignerParams =
  GetEscrowsFromIndexerParams & {
    /**
     * Dirección del usuario que firma la transacción del contrato.
     */
    signer: string;
  };

export type GetEscrowsFromIndexerByRoleParams = GetEscrowsFromIndexerParams & {
  /**
   * Rol del usuario. Obligatorio
   */
  role: Role;

  /**
   * Dirección del propietario de los escrows. Si quieres obtener todos los escrows de un rol específico, puedes usar este parámetro. Pero con este parámetro, no puedes usar el parámetro signer.
   */
  roleAddress: string;
};

export type GetEscrowFromIndexerByContractIdsParams = {
  /**
   * IDs (direcciones) que identifican los contratos de escrow.
   */
  contractIds: string[];

  /**
   * Si es true, los escrows se validarán en la blockchain para garantizar la consistencia de los datos.
   * Esto realiza un paso adicional de verificación para confirmar que los datos del escrow
   * devueltos por el indexador coinciden con el estado actual en la blockchain.
   * Usa esto cuando necesites asegurar la información de escrow más actualizada y precisa.
   * Si activas este parámetro, tu solicitud tardará más en completarse.
   */
  validateOnChain?: boolean;
};

// ----------------- Liberar fondos -----------------
/**
 * Carga útil para liberar fondos en liberación única
 */
export type SingleReleaseReleaseFundsPayload = {
  /**
   * ID (dirección) que identifica el contrato de escrow
   */
  contractId: string;

  /**
   * Dirección del usuario encargado de liberar los fondos del escrow al proveedor del servicio.
   */
  releaseSigner: string;
};

/**
 * Carga útil para liberar fondos en múltiples liberaciones
 */
export type MultiReleaseReleaseFundsPayload =
  SingleReleaseReleaseFundsPayload & {
    /**
     * Índice del hito que se va a liberar
     */
    milestoneIndex: string;
  };

// ----------------- Obtener saldo -----------------
/**
 * Parámetros para obtener saldo
 */
export type GetBalanceParams = {
  /**
   * Direcciones de los escrows para obtener el saldo
   */
  addresses: string[];
};

// ----------------- Actualizar desde hash de transacción -----------------
/**
 * Carga útil para actualizar datos del escrow desde un hash de transacción.
 */
export type UpdateFromTxHashPayload = {
  /**
   * Hash de transacción a utilizar para la actualización.
   */
  txHash: string;
};