path: root/src/backend/taler-merchant-httpd_contract.h

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

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Lesser 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 taler-merchant-httpd_contract.h
 * @brief shared logic for contract terms handling
 * @author Christian Blättler
 */
#include "taler-merchant-httpd.h"
#include <jansson.h>


/**
 * Possible versions of the contract terms.
 */
enum TALER_MerchantContractVersion
{

  /**
   * Version 0
   */
  TALER_MCV_V0 = 0,

  /**
   * Version 1
   */
  TALER_MCV_V1 = 1
};

/**
* Contract fields specific to v0 contract format.
*/
struct TALER_MerchantContractV0
{
  /**
  * Summary of the order.
  */
  const char *summary;

  /**
  * Internationalized summary.
  */
  json_t *summary_i18n;

  /**
  * URL that will show that the order was successful
  * after it has been paid for.
  */
  const char *fulfillment_url;

  /**
  * Message shown to the customer after paying for the order.
  * Either fulfillment_url or fulfillment_message must be specified.
  */
  const char *fulfillment_message;

  /**
  * Map from IETF BCP 47 language tags to localized fulfillment messages.
  */
  json_t *fulfillment_message_i18n;

  /**
  * Array of products that are part of the purchase.
  */
  const json_t *products;

  /**
  * Gross amount value of the contract. Used to
  * compute @e max_stefan_fee.
  */
  struct TALER_Amount brutto;

  /**
  * Maximum fee as given by the client request.
  */
  struct TALER_Amount max_fee;
};

/**
* Possible input types for the contract terms.
*/
enum TALER_MerchantContractV1InputType
{

  /**
   * Input type coin
   */
  TALER_MCIT_COIN = 0,

  /**
   * Input type token
   */
  TALER_MCIT_TOKEN = 1
};

/**
* Contract input (part of the v1 contract terms).
*/
struct TALER_MerchantContractV1Input
{
  /**
  * Type of the input.
  */
  enum TALER_MerchantContractV1InputType type;

  union
  {
    /**
    * Coin-based input.
    */
    struct
    {
      /**
      * Price to be paid.
      */
      struct TALER_Amount price;
    } coin;

    /**
    * Token-based input.
    */
    struct
    {
      /**
      * Hash over the public key used to sign the type of subscription
      * token required.
      */
      struct TALER_TokenFamilyPublicKeyHash h_issuer;

      /**
      * Number of tokens of this type required. Defaults to one if the
      * field is not provided.
      */
      unsigned int number;
    } token;
  } details;
};

/**
* Possible output types for the contract terms.
*/
enum TALER_MerchantContractV1OutputType
{

  /**
   * Output type coin
   */
  TALER_MCOT_COIN = 0,

  /**
   * Output type token
   */
  TALER_MCOT_TOKEN = 1,

  /**
   * Output type tax-receipt
   */
  TALER_MCOT_TAX_RECEIPT = 2

};

/**
* Possible token output classes.
*/
enum TALER_MerchantContractV1OutputTokenClass
{

  /**
   * Token class subscription
   */
  TALER_MCOTC_SUBSCRIPTION = 0,

  /**
   * Token class discount
   */
  TALER_MCOTC_DISCOUNT = 1
};

/**
* Contract output (part of the v1 contract terms).
*/
struct TALER_MerchantContractV1Output
{
  /**
  * Type of the output.
  */
  enum TALER_MerchantContractV1OutputType type;

  union
  {
    /**
    * Coin-based output.
    */
    struct {
      /**
      * Coins that will be yielded. This excludes any applicable withdraw fees.
      */
      struct TALER_Amount brutto_yield;

      /**
      * Base URL of the exchange that will issue the coins.
      */
      const char *exchange_url;
    } coin;

    /**
    * Tax-receipt output.
    */
    struct
    {
      /**
      * Base URL of the donation authority that will issue the tax receipt.
      */
      const char *donau_url;
    } tax_receipt;

    /**
    * Token-based output.
    */
    struct
    {
      /**
      * Label of the token authority in the 'token_authorities' array on the top-level.
      */
      const char *token_authority_label;

      /**
      * Must a wallet understand this token type to process contracts that
      * consume or yield it?
      */
      bool critical;

      /**
      * Class of token that will be yielded.
      */
      enum TALER_MerchantContractV1OutputTokenClass token_class;

      /**
      * Information about the class of token that will be yielded.
      */
      union
      {
        /**
        * Subscription token.
        */
        struct
        {
          /**
          * When does the subscription period start?
          */
          struct GNUNET_TIME_Absolute start_date;

          /**
          * When does the subscription period end?
          */
          struct GNUNET_TIME_Absolute end_date;

          /**
          * Array of domain names where this subscription can be safely used
          * (e.g. the issuer warrants that these sites will re-issue tokens of
          * this type if the respective contract says so). May contain "*" for
          * any domain or subdomain.
          */
          const char **trusted_domains;

          /**
          * Length of the @e trusted_domains array.
          */
          unsigned int trusted_domains_len;
        } subscription;

        /**
        * Discount token.
        */
        struct
        {
          /**
          * Array of domain names where this discount token is intended to be
          * used. May contain "*" for any domain or subdomain. Users should be
          * warned about sites proposing to consume discount tokens of this
          * type that are not in this list that the merchant is accepting a
          * coupon from a competitor and thus may be attaching different
          * semantics (like get 20% discount for my competitors 30% discount
          * token).
          */
          const char **expected_domains;

          /**
          * Length of the @e expected_domains array.
          */
          unsigned int expected_domains_len;

        } discount;
      } details;
    } token;
  } details;
};

/**
* Contract choice (part of the v1 contract terms).
*/
struct TALER_MerchantContractV1Choice
{
  /**
  * Summary of the order.
  */
  const char *summary;

  /**
  * Internationalized summary.
  */
  json_t *summary_i18n;

  /**
  * URL that will show that the order was successful
  * after it has been paid for.
  */
  const char *fulfillment_url;

  /**
  * Message shown to the customer after paying for the order.
  * Either fulfillment_url or fulfillment_message must be specified.
  */
  const char *fulfillment_message;

  /**
  * Map from IETF BCP 47 language tags to localized fulfillment messages.
  */
  json_t *fulfillment_message_i18n;

  /**
  * Array of products that are part of the purchase.
  */
  const json_t *products;

  /**
  * List of inputs the wallet must provision (all of them) to satisfy the
  * conditions for the contract.
  */
  struct TALER_MerchantContractV1Input *inputs;

  /**
  * Length of the @e inputs array.
  */
  unsigned int inputs_len;

  /**
  * List of outputs the merchant promises to yield (all of them) once
  * the contract is paid.
  */
  struct TALER_MerchantContractV1Output *ouputs;

  /**
  * Length of the @e outputs array.
  */
  unsigned int outputs_len;
};

/**
* Contract fields specific to v1 contract format.
*/
struct TALER_MerchantContractV1
{
  /**
  * Array of possible specific contracts the wallet/customer may choose
  * from by selecting the respective index when signing the deposit
  * confirmation.
  */
  struct TALER_MerchantContractV1Choice *choices;

  /**
  * Length of the @e choices array.
  */
  unsigned int choices_len;

  /**
  * TODO: This was moved out a level: Change design document according to this.
  * Array of token authorities.
  */
  struct
  {
    /**
    * Label of the token authority.
    */
    const char *label;

    /**
    * Human-readable description of the semantics of the tokens issued by
    * this authority.
    */
    const char *summary;

    /**
    * Map from IETF BCP 47 language tags to localized summaries.
    */
    json_t *summary_i18n;

    /**
    * Public key used to validate tokens signed by this authority.
    */
    struct TALER_TokenFamilyPublicKey key;

    /**
    * When will tokens signed by this key expire?
    */
    struct GNUNET_TIME_Timestamp token_expiration;

  } *token_authorities;

  /**
  * Length of the @e token_authorities array.
  */
  unsigned int token_authorities_len;

  /**
  * TODO: Model this
  * Fee limits and wire account details by currency.
  * limits: { [currency:string] : CurrencyLimit };
  */
};

/**
* Struct to hold contract terms in v0 and v1 format. Shared fields are on the
* top level, while version specific fields are in the respective sub-structs.
*/
struct TALER_MerchantContract
{
  /**
  * URL where the same contract could be ordered again (if available).
  */
  const char *public_reorder_url;

  /**
  * Our order ID.
  */
  const char *order_id;

  /**
  * Merchant base URL.
  */
  char *merchant_base_url;

  /**
  * Timestamp of the order.
  */
  struct GNUNET_TIME_Timestamp timestamp;

  /**
  * Deadline for refunds.
  */
  struct GNUNET_TIME_Timestamp refund_deadline;

  /**
  * Specifies for how long the wallet should try to get an
  * automatic refund for the purchase.
  */
  struct GNUNET_TIME_Relative auto_refund;

  /**
  * Payment deadline.
  */
  struct GNUNET_TIME_Timestamp pay_deadline;

  /**
  * Wire transfer deadline.
  */
  struct GNUNET_TIME_Timestamp wire_deadline;

  /**
  * Delivery date.
  */
  struct GNUNET_TIME_Timestamp delivery_date;

  /**
  * Delivery location.
  */
  json_t *delivery_location;

  /**
  * Nonce generated by the wallet and echoed by the merchant
  * in this field when the proposal is generated.
  */
  const char *nonce;

  /**
  * Extra data that is only interpreted by the merchant frontend.
  */
  const json_t *extra;

  /**
  * Specified version of the order.
  */
  enum TALER_MerchantContractVersion version;

  /**
  * Contract information in v0 format.
  */
  struct TALER_MerchantContractV0 v0;

  /**
  * Order information passed in in v1 format.
  */
  struct TALER_MerchantContractV1 v1;
};

/**
 * Serialize @a contract to a JSON object, ready to be stored in the database.
 * The @a contract can be of v0 or v1.
 *
 * @param[in] contract contract struct to serialize
 * @param[out] out serialized contract as JSON object
 * @return #GNUNET_OK on success
 *         #GNUNET_NO if @a contract was not valid
 *         #GNUNET_SYSERR on failure
 */
enum GNUNET_GenericReturnValue
TMH_serialize_contract (const struct TALER_MerchantContract *contract,
                        json_t **out);

enum GNUNET_GenericReturnValue
TMH_serialize_contract_v0 (const struct TALER_MerchantContract *contract,
                           const struct TMH_MerchantInstance *instance,
                           const struct TMH_WireMethod *wm,
                           json_t *exchanges,
                           json_t *products,
                           struct TALER_Amount *max_fee,
                           json_t **out);

enum GNUNET_GenericReturnValue
TMH_serialize_contract_v1 (const struct TALER_MerchantContract *contract,
                           json_t **out);