.. _module-utility-credential-app-v0-model-billing-31258: Utility.Credential.App.V0.Model.Billing ======================================= Templates --------- .. _type-utility-credential-app-v0-model-billing-billingparamsadjustmentrequest-22699: **template** `BillingParamsAdjustmentRequest `_ Represents a request from the ``issuer`` to adjust the billing parameters of the given credential billing\. Signatory\: operator, issuer .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - operator - `Party `_ - Utility operator\. * - issuer - `Party `_ - Credential issuer\. * - holder - `Party `_ - Credential holder\. * - params - :ref:`BillingParams ` - Billing parameters for the credential\. * - credentialId - `Text `_ - Identifier of the credential whose billing parameters the ``issuer`` requests to adjust\. + **Choice** Archive Controller\: operator, issuer Returns\: () (no fields) + .. _type-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestaccept-9999: **Choice** `BillingParamsAdjustmentRequest_Accept `_ Accepts this request\. Controller\: holder Returns\: `BillingParamsAdjustmentRequest_Accept_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - credentialBillingCid - `ContractId `_ `CredentialBilling `_ - Credential billing to be adjusted\. + .. _type-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestcancel-57173: **Choice** `BillingParamsAdjustmentRequest_Cancel `_ Cancels this request\. Allowed for both the ``issuer`` and the ``holder``\. Controller\: actor \`oneOf\` \[issuer, holder\] Returns\: `BillingParamsAdjustmentRequest_Cancel_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - actor - `Party `_ - .. _type-utility-credential-app-v0-model-billing-canceledcredentialbilling-63484: **template** `CanceledCredentialBilling `_ A canceled credential billing\. Signatory\: (DA\.Internal\.Record\.getField @\"operator\" payload) .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - payload - `CredentialBilling `_ - Credential billing payload that was cancelled\. * - cancelledBy - `Party `_ - Party that initiated the cancellation\. * - cancelledAt - `Time `_ - Time when the credential was cancelled\. * - returnedUserAmountCc - `Decimal `_ - Amount of CC that was paid out to the user (before CC fees)\. + **Choice** Archive Controller\: (DA\.Internal\.Record\.getField @\"operator\" payload) Returns\: () (no fields) .. _type-utility-credential-app-v0-model-billing-credentialbilling-78403: **template** `CredentialBilling `_ A credential billing\. Signatory\: operator, issuer, holder .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - operator - `Party `_ - Utility operator\. * - issuer - `Party `_ - Credential issuer\. * - holder - `Party `_ - Credential holder\. * - dso - `Party `_ - DSO (Decentralized Synchronizer Operations) party\. * - credentialId - `Text `_ - Identifier of the credential this billing refers to * - params - :ref:`BillingParams ` - Billing parameters for the credential\. * - balanceState - :ref:`BalanceState ` - Balances determining the split of the deposit amount between provider and user\. * - billingState - :ref:`BillingState ` - State of the billing process\. * - deposits - \[`ContractId `_ `LockedAmulet `_\] - Deposit to cover upcoming credential charges and user pay\-outs\. + **Choice** Archive Controller\: operator, issuer, holder Returns\: () (no fields) + .. _type-utility-credential-app-v0-model-billing-credentialbillingadjustbillingparams-65118: **Choice** `CredentialBilling_AdjustBillingParams `_ Adjusts the billing parameters for the credential\. We allow this unilaterally, as the holder can cancel at any time\. Controller\: issuer Returns\: `CredentialBilling_AdjustBillingParams_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - newParams - :ref:`BillingParams ` - New billing parameters\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingbill-59526: **Choice** `CredentialBilling_Bill `_ Charges the credential fee on a pro\-rata basis between the last charge and now\. Fees incurred from transferring and locking CC are paid by the recipient (the issuer)\. Controller\: operator Returns\: `CredentialBilling_Bill_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - appTransferContext - `AppTransferContext `_ - Coin transfer context\. * - enableFeeRecord - `Optional `_ `Bool `_ - Create a fee record for the billing (for accounting purposes)\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingcancel-28513: **Choice** `CredentialBilling_Cancel `_ Cancels the credential billing\. We allow this unilaterally from both sides\. It is up to the issuer to revoke the associated credential upon billing cancelation\. The transfer fees for returning the deposit are paid by the actor\. Controller\: actor \`oneOf\` \[issuer, holder\] Returns\: `CredentialBilling_Cancel_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - actor - `Party `_ - Party that initiated the cancellation\. * - appTransferContext - `AppTransferContext `_ - Reference data for transferring the remaining CC\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingdistribute-13294: **Choice** `CredentialBilling_Distribute `_ Allows the credential issuer to distribute coins to the credential holder\. Fees are paid by the sender (the issuer)\. Controller\: issuer Returns\: `CredentialBilling_Distribute_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - amountUsd - `Decimal `_ - Amount to distribute (in USD)\. This is the exact amount that the holder receives, since fees are paid by the sender\. * - coinCids - \[`ContractId `_ `Amulet `_\] - Coins to distribute\. This needs to cover the amount to distribute plus fees\. If the total value of the coins exceeds the amount required, the remaining change is returned to the sender\. * - appTransferContext - `AppTransferContext `_ - Coin transfer context\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingdistributeandadjustdeposit-70078: **Choice** `CredentialBilling_DistributeAndAdjustDeposit `_ Allows the credential issuer to distribute coins to and top up the deposit of the holder\. Coins are used to adjust the deposit to a target, with the remainder transferred to the holder\. If the amount to distribute plus the current deposit amount does not reach this target, the full amount to distribute is used to top up the deposit (and no remainder is transferred to the holder)\. Fees are paid by the sender (the issuer)\. Controller\: issuer Returns\: `CredentialBilling_DistributeAndAdjustDeposit_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - amountUsd - `Decimal `_ - Amount to distribute (in USD)\. This is the exact amount that the holder receives, since fees are paid by the sender\. * - coinCids - \[`ContractId `_ `Amulet `_\] - Coins to top up and distribute\. This needs to cover the amount to distribute plus fees\. If the total value of the coins exceeds the amount required, the remaining change is returned to the sender\. * - appTransferContext - `AppTransferContext `_ - Coin transfer context\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingrequesttoadjustbillingparams-84613: **Choice** `CredentialBilling_RequestToAdjustBillingParams `_ Creates a request from the ``issuer`` to adjust the billing parameters for the credential\. Controller\: issuer Returns\: `CredentialBilling_RequestToAdjustBillingParams_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - newParams - :ref:`BillingParams ` - New billing parameters\. + .. _type-utility-credential-app-v0-model-billing-credentialbillingtopup-97242: **Choice** `CredentialBilling_TopUp `_ Top up the deposit by the specified amount\. The target deposit amount is used to cap the new deposit\. Fees are paid by the sender (the holder)\. Controller\: holder, operator Returns\: `CredentialBilling_TopUp_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - amountUsd - `Decimal `_ - Amount to top up (in USD)\. Since fees are paid by the sender, the deposit will be topped up by this full amount\. * - coinCids - \[`ContractId `_ `Amulet `_\] - Coins to top up\. This needs to cover the amount to top up plus fees\. If the total value of the coins exceeds the amount required, the remaining change is returned to the sender\. * - appTransferContext - `AppTransferContext `_ - Coin transfer context\. Data Types ---------- .. _type-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestacceptresult-31744: **data** `BillingParamsAdjustmentRequest_Accept_Result `_ Result of the ``BillingParamsAdjustmentRequest_Accept`` choice\. .. _constr-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestacceptresult-46549: `BillingParamsAdjustmentRequest_Accept_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - credentialBillingCid - `ContractId `_ `CredentialBilling `_ - .. _type-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestcancelresult-87334: **data** `BillingParamsAdjustmentRequest_Cancel_Result `_ Result of the ``BillingParamsAdjustmentRequest_Cancel`` choice\. .. _constr-utility-credential-app-v0-model-billing-billingparamsadjustmentrequestcancelresult-51291: `BillingParamsAdjustmentRequest_Cancel_Result `_ .. _type-utility-credential-app-v0-model-billing-credentialbillingadjustbillingparamsresult-31839: **data** `CredentialBilling_AdjustBillingParams_Result `_ Result of adjusting the credential parameters\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingadjustbillingparamsresult-42010: `CredentialBilling_AdjustBillingParams_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - newCredentialBillingCid - `ContractId `_ `CredentialBilling `_ - New credential billing with updated parameters\. .. _type-utility-credential-app-v0-model-billing-credentialbillingbillresult-6503: **data** `CredentialBilling_Bill_Result `_ Result of billing a credential\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingbillresult-55592: `CredentialBilling_Bill_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - billingCycleParams - :ref:`BillingCycleParams ` - Parameters used for executing the billing cycle\. * - transferResult - `Optional `_ `TransferResult `_ - Result of the coin transfer for a successful billing\. * - newCredentialBillingCid - `ContractId `_ `CredentialBilling `_ - New billing with updated balances and billing state\. * - feeRecordCid - `Optional `_ (`ContractId `_ :ref:`FeeRecord `) - Information on the CC fees burned as part of the transfer\. .. _type-utility-credential-app-v0-model-billing-credentialbillingcancelresult-46550: **data** `CredentialBilling_Cancel_Result `_ Result of canceling a credential\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingcancelresult-49129: `CredentialBilling_Cancel_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - canceledCredentialBillingCid - `ContractId `_ `CanceledCredentialBilling `_ - Canceled credential billing cid\. .. _type-utility-credential-app-v0-model-billing-credentialbillingdistributeandadjustdepositresult-15795: **data** `CredentialBilling_DistributeAndAdjustDeposit_Result `_ Result of the ``CredentialBilling_DistributeAndAdjustDeposit`` choice\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingdistributeandadjustdepositresult-75912: `CredentialBilling_DistributeAndAdjustDeposit_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - newCredentialBillingCid - `ContractId `_ `CredentialBilling `_ - New credential billing with updated deposit\. * - transferResult - `TransferResult `_ - Result of the coin transfer\. .. _type-utility-credential-app-v0-model-billing-credentialbillingdistributeresult-17731: **data** `CredentialBilling_Distribute_Result `_ Result of the ``CredentialBilling_Distribute`` choice\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingdistributeresult-73640: `CredentialBilling_Distribute_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - transferResult - `TransferResult `_ - Result of the coin transfer\. .. _type-utility-credential-app-v0-model-billing-credentialbillingrequesttoadjustbillingparamsresult-92778: **data** `CredentialBilling_RequestToAdjustBillingParams_Result `_ Result of the ``CredentialBilling_RequestToAdjustBillingParams`` choice\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingrequesttoadjustbillingparamsresult-54285: `CredentialBilling_RequestToAdjustBillingParams_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - requestCid - `ContractId `_ `BillingParamsAdjustmentRequest `_ - .. _type-utility-credential-app-v0-model-billing-credentialbillingtopupresult-15391: **data** `CredentialBilling_TopUp_Result `_ Result of the ``CredentialBilling_TopUp`` choice\. .. _constr-utility-credential-app-v0-model-billing-credentialbillingtopupresult-88390: `CredentialBilling_TopUp_Result `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - newCredentialBillingCid - `ContractId `_ `CredentialBilling `_ - New credential billing with updated deposit\. Functions --------- .. _function-utility-credential-app-v0-model-billing-validatebalancestate-96229: `validateBalanceState `_ \: :ref:`BalanceState ` \-\> `Update `_ () Check that the balance state satisfies the accounting equations\. .. _function-utility-credential-app-v0-model-billing-fetchandvalidatebillingcontext-78257: `fetchAndValidateBillingContext `_ \: `Party `_ \-\> `Party `_ \-\> `AppTransferContext `_ \-\> `Update `_ :ref:`BillingContext ` Fetch the billing context components from the ledger and validate them\. .. _function-utility-credential-app-v0-model-billing-getdepositholdingfees-57867: `getDepositHoldingFees `_ \: :ref:`BillingContext ` \-\> `ContractId `_ `LockedAmulet `_ \-\> `Update `_ `Decimal `_ Calculate the holding fees pending on the deposited ``LockedAmulet`` since its creation\. .. _function-utility-credential-app-v0-model-billing-computebillingcycleparams-68875: `computeBillingCycleParams `_ \: :ref:`BillingContext ` \-\> :ref:`BillingParams ` \-\> :ref:`BillingState ` \-\> :ref:`BillingCycleParams ` Compute the billing parameters for the next billing cycle\. .. _function-utility-credential-app-v0-model-billing-executebill-5047: `executeBill `_ \: `CredentialBilling `_ \-\> `AppTransferContext `_ \-\> `Optional `_ `Bool `_ \-\> `Update `_ `CredentialBilling_Bill_Result `_ Body of the billing choice\. Factored out for improved readability\. All fees for billing are paid by the issuer, as the user already pays for the credential\. .. _function-utility-credential-app-v0-model-billing-executedistribute-48923: `executeDistribute `_ \: `CredentialBilling `_ \-\> `Decimal `_ \-\> \[`ContractId `_ `Amulet `_\] \-\> `AppTransferContext `_ \-\> `Update `_ `CredentialBilling_Distribute_Result `_ Distribute coins to the credential holder\. .. _function-utility-credential-app-v0-model-billing-executetopup-29049: `executeTopUp `_ \: `CredentialBilling `_ \-\> `Decimal `_ \-\> \[`ContractId `_ `Amulet `_\] \-\> `AppTransferContext `_ \-\> `Update `_ `CredentialBilling_TopUp_Result `_ Top up the deposit with an extra amount\. .. _function-utility-credential-app-v0-model-billing-calculatenewbalancestate-86765: `calculateNewBalanceState `_ \: :ref:`BillingCycleParams ` \-\> :ref:`BalanceState ` \-\> :ref:`BalanceState ` Compute the new balance state after running this billing cycle\. If, after billing, the user's deposit is too low then there is a chance we might not be able to lock it again for the desired lock period\. To address this we fully reimburse the user deposit amount when if falls below a certain threshold (currently set to 1 USD)\. .. _function-utility-credential-app-v0-model-billing-cancelcredentialbilling-50663: `cancelCredentialBilling `_ \: `CredentialBilling `_ \-\> `CredentialBilling_Cancel `_ \-\> `Update `_ `CredentialBilling_Cancel_Result `_ .. _function-utility-credential-app-v0-model-billing-computeccfees-54145: `computeCcFees `_ \: :ref:`BillingContext ` \-\> `Party `_ \-\> \[`TransferOutput `_\] \-\> `Update `_ `Decimal `_ Compute the CC fees for a set of transfers\. .. _function-utility-credential-app-v0-model-billing-unlockdeposit-67449: `unlockDeposit `_ \: :ref:`BillingContext ` \-\> `ContractId `_ `LockedAmulet `_ \-\> `Update `_ `TransferInput `_ Unlock an existing deposit and return the coin as InputAmulet for a transfer\.