/*
   This file is part of TALER
   Copyright (C) 2026 Taler Systems SA

   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
   Foundation; either version 3, or (at your option) any later version.

   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

   You should have received a copy of the GNU General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
/**
 * @file src/include/exchange-database/get_open_legitimization_measure.h
 * @brief implementation of the get_open_legitimization_measure function
 * @author Christian Grothoff
 */
#ifndef EXCHANGE_DATABASE_GET_OPEN_LEGITIMIZATION_MEASURE_H
#define EXCHANGE_DATABASE_GET_OPEN_LEGITIMIZATION_MEASURE_H

#include "taler/taler_util.h"
#include "exchangedb_lib.h"


/**
 * Find a KYC measure that the exchange imposed on @a h_payto and that has not
 * yet produced a decision.  Such a measure is the exchange's own explanation
 * for why it is not paying the account out.
 *
 * A measure counts as satisfied once some `legitimization_processes` row
 * refers to it *and* the account has a `legitimization_outcomes` row that was
 * decided no earlier than that process started.  Both halves are needed: a
 * process that was started and abandoned decides nothing, and an outcome that
 * predates the process belongs to an earlier measure.
 *
 * This deliberately uses only columns that `taler-auditor-sync` replicates, so
 * that an external auditor reaches the same verdict as an internal one.  In
 * particular it cannot look at `legitimization_measures.is_finished` or
 * `legitimization_processes.finished`, neither of which is replicated.
 *
 * @param pg the database context
 * @param h_payto normalized hash of the payto URI of the account
 * @param[out] legitimization_measure_serial_id set to the lowest such measure
 * @param[out] start_time set to when that measure was imposed; the exchange
 *        writes this column at full precision, so it is not a rounded
 *        timestamp
 * @return #GNUNET_DB_STATUS_SUCCESS_NO_RESULTS if every measure on the
 *         account was decided, including if there never was one
 */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_get_open_legitimization_measure (
  struct TALER_EXCHANGEDB_PostgresContext *pg,
  const struct TALER_NormalizedPaytoHashP *h_payto,
  uint64_t *legitimization_measure_serial_id,
  struct GNUNET_TIME_Absolute *start_time);

#endif
