diff options
Diffstat (limited to 'src/backend/taler-merchant-httpd_contract.h')
| -rw-r--r-- | src/backend/taler-merchant-httpd_contract.h | 592 |
1 files changed, 592 insertions, 0 deletions
diff --git a/src/backend/taler-merchant-httpd_contract.h b/src/backend/taler-merchant-httpd_contract.h new file mode 100644 index 00000000..b1e3938c --- /dev/null +++ b/src/backend/taler-merchant-httpd_contract.h @@ -0,0 +1,592 @@ +/* + 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 <gnunet/gnunet_time_lib.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 +}; + +/** + * Possible token kinds. + */ +enum TALER_MerchantContractTokenKind +{ + + /** + * Subscription token kind + */ + TALER_MCTK_SUBSCRIPTION = 0, + + /** + * Discount token kind + */ + TALER_MCTK_DISCOUNT = 1 +}; + +/** + * Possible input types for the contract terms. + */ +enum TALER_MerchantContractInputType +{ + + /** + * Input type invalid + */ + TALER_MCIT_INVALID = 0, + + /** + * Input type coin + */ + TALER_MCIT_COIN = 1, + + /** + * Input type token + */ + TALER_MCIT_TOKEN = 2 +}; + +/** + * Contract input (part of the v1 contract terms). + */ +struct TALER_MerchantContractInput +{ + /** + * Type of the input. + */ + enum TALER_MerchantContractInputType type; + + union + { + /** + * Coin-based input (ration). (Future work, only here for reference) + */ + // struct + // { + // /** + // * Price to be paid. + // */ + // struct TALER_Amount price; + + // /** + // * Base URL of the ration authority. + // */ + // const char *ration_authority_url; + // } coin; + + /** + * Token-based input. + */ + struct + { + /** + * Slug of the token family to be used. + */ + const char *token_family_slug; + + /** + * Start time of the validity period of the token. Base on this timestamp + * the wallet can find the correct key for this token in token_authorities. + */ + struct GNUNET_TIME_Timestamp valid_after; + + /** + * Number of tokens of this type required. Defaults to one if the + * field is not provided. + */ + unsigned int count; + } token; + } details; +}; + +/** + * Possible output types for the contract terms. + */ +enum TALER_MerchantContractOutputType +{ + + /** + * Invalid output type + */ + TALER_MCOT_INVALID = 0, + + /** + * Output type coin + */ + TALER_MCOT_COIN = 1, + + /** + * Output type token + */ + TALER_MCOT_TOKEN = 2, + + /** + * Output type tax-receipt + */ + TALER_MCOT_TAX_RECEIPT = 3 + +}; + +/** + * Contract output (part of the v1 contract terms). + */ +struct TALER_MerchantContractOutput +{ + /** + * Type of the output. + */ + enum TALER_MerchantContractOutputType 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 + { + /** + * Slug of the token family to be issued. + */ + const char *token_family_slug; + + /** + * Start time of the validity period of the token. Base on this timestamp + * the wallet can find the correct key for this token in token_authorities. + */ + struct GNUNET_TIME_Timestamp valid_after; + + /** + * Number of tokens of this type required. Defaults to one if the + * field is not provided. + */ + unsigned int count; + } token; + } details; +}; + +/** + * Contract choice (part of the v1 contract terms). + */ +struct TALER_MerchantContractChoice +{ + /** + * List of inputs the wallet must provision (all of them) to satisfy the + * conditions for the contract. + */ + struct TALER_MerchantContractInput *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_MerchantContractOutput *outputs; + + /** + * Length of the @e outputs array. + */ + unsigned int outputs_len; +}; + +struct TALER_MerchantContractLimits +{ + /** + * Currency these limits are for. + */ + char currency[TALER_CURRENCY_LEN]; + + /** + * The hash of the merchant instance's wire details. + */ + struct TALER_MerchantWireHashP h_wire; + + /** + * Wire transfer method identifier for the wire method associated with ``h_wire``. + * The wallet may only select exchanges via a matching auditor if the + * exchange also supports this wire method. + * The wire transfer fees must be added based on this wire transfer method. + */ + char *wire_method; + + /** + * Maximum total deposit fee accepted by the merchant for this contract. + */ + struct TALER_Amount max_fee; +}; + +struct TALER_MerchantContractTokenAuthority +{ + /** + * Label of the token authority. + */ + const char *label; + + /** + * Human-readable description of the semantics of the tokens issued by + * this authority. + */ + char *description; + + /** + * Map from IETF BCP 47 language tags to localized description. + */ + json_t *description_i18n; + + /** + * Public key used to validate tokens signed by this authority. + */ + struct TALER_TokenFamilyPublicKey *pub; + + /** + * When will tokens signed by this key expire? + */ + struct GNUNET_TIME_Timestamp token_expiration; + + /** + * Must a wallet understand this token type to process contracts that + * consume or yield it? + */ + bool critical; + + /** + * Kind of the token. + */ + enum TALER_MerchantContractTokenKind kind; + + /** + * Kind-specific information about the token. + */ + union + { + /** + * Subscription token. + */ + struct + { + /** + * When does the subscription period start? + */ + struct GNUNET_TIME_Timestamp start_date; + + /** + * When does the subscription period end? + */ + struct GNUNET_TIME_Timestamp 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; +}; + +/** + * Struct to hold contract terms in v0 and v1 format. v0 contracts are modelled + * as a v1 contract with a single choice and no inputs and outputs. Use the + * version field to explicitly differentiate between v0 and v1 contracts. + */ +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; + + /** + * Merchant information. + */ + struct + { + /** + * Legal name of the instance + */ + char *name; + + /** + * Merchant's site url + */ + char *website; + + /** + * Email contact for customers + */ + char *email; + + /** + * merchant's logo data uri + */ + char *logo; + + /** + * Merchant address + */ + json_t *address; + + /** + * Jurisdiction of the business + */ + json_t *jurisdiction; + } merchant; + + /** + * Price to be paid for the transaction. Could be 0. The price is in addition + * to other instruments, such as rations and tokens. + * The exchange will subtract deposit fees from that amount + * before transferring it to the merchant. + */ + struct TALER_Amount brutto; + + /** + * Summary of the contract. + */ + const char *summary; + + /** + * Internationalized summary. + */ + json_t *summary_i18n; + + /** + * URL that will show that the contract was successful + * after it has been paid for. + */ + const char *fulfillment_url; + + /** + * Message shown to the customer after paying for the contract. + * 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; + + /** + * Timestamp of the contract. + */ + 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 contract. + */ + enum TALER_MerchantContractVersion version; + + /** + * Array of possible specific contracts the wallet/customer may choose + * from by selecting the respective index when signing the deposit + * confirmation. + */ + struct TALER_MerchantContractChoice *choices; + + /** + * Length of the @e choices array. + */ + unsigned int choices_len; + + /** + * Array of token authorities. + */ + struct TALER_MerchantContractTokenAuthority *token_authorities; + + /** + * Length of the @e token_authorities array. + */ + unsigned int token_authorities_len; + + /** + * Maximum fee as given by the client request. + */ + struct TALER_Amount max_fee; + + // TODO: Add exchanges array +}; + +enum TALER_MerchantContractInputType +TMH_string_to_contract_input_type (const char *str); + +enum TALER_MerchantContractOutputType +TMH_string_to_contract_output_type (const char *str); + +/** + * 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[in] instance merchant instance for this contract + * @param[in] exchanges JSON array of exchanges + * @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, + const struct TMH_MerchantInstance *instance, + json_t *exchanges, + json_t **out); + +enum GNUNET_GenericReturnValue +TMH_serialize_contract_v0 (const struct TALER_MerchantContract *contract, + const struct TMH_MerchantInstance *instance, + json_t *exchanges, + json_t **out); + +enum GNUNET_GenericReturnValue +TMH_serialize_contract_v1 (const struct TALER_MerchantContract *contract, + const struct TMH_MerchantInstance *instance, + json_t *exchanges, + json_t **out);
\ No newline at end of file |