Utility.Credential.App.V0.Model.Billing

Templates

template BillingParamsAdjustmentRequest

Represents a request from the issuer to adjust the billing parameters of the given credential billing.

Signatory: operator, issuer

Field	Type	Description
operator	Party	Utility operator.
issuer	Party	Credential issuer.
holder	Party	Credential holder.
params	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)

• Choice BillingParamsAdjustmentRequest_Accept

  Accepts this request.

  Controller: holder

  Returns: BillingParamsAdjustmentRequest_Accept_Result

  Field	Type	Description
  credentialBillingCid	ContractId CredentialBilling	Credential billing to be adjusted.

• Choice BillingParamsAdjustmentRequest_Cancel

  Cancels this request. Allowed for both the issuer and the holder.

  Controller: actor `oneOf` [issuer, holder]

  Returns: BillingParamsAdjustmentRequest_Cancel_Result

  Field	Type	Description
  actor	Party

template CanceledCredentialBilling

A canceled credential billing.

Signatory: (DA.Internal.Record.getField @"operator" payload)

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)

template CredentialBilling

A credential billing.

Signatory: operator, issuer, holder

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	BillingParams	Billing parameters for the credential.
balanceState	BalanceState	Balances determining the split of the deposit amount between provider and user.
billingState	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)

• 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

  Field	Type	Description
  newParams	BillingParams	New billing parameters.

• 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

  Field	Type	Description
  appTransferContext	AppTransferContext	Coin transfer context.
  enableFeeRecord	Optional Bool	Create a fee record for the billing (for accounting purposes).

• 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

  Field	Type	Description
  actor	Party	Party that initiated the cancellation.
  appTransferContext	AppTransferContext	Reference data for transferring the remaining CC.

• 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

  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.

• 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

  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.

• Choice CredentialBilling_RequestToAdjustBillingParams

  Creates a request from the issuer to adjust the billing parameters for the credential.

  Controller: issuer

  Returns: CredentialBilling_RequestToAdjustBillingParams_Result

  Field	Type	Description
  newParams	BillingParams	New billing parameters.

• 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

  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

data BillingParamsAdjustmentRequest_Accept_Result

Result of the BillingParamsAdjustmentRequest_Accept choice.

BillingParamsAdjustmentRequest_Accept_Result

Field	Type	Description
credentialBillingCid	ContractId CredentialBilling

data BillingParamsAdjustmentRequest_Cancel_Result

Result of the BillingParamsAdjustmentRequest_Cancel choice.

BillingParamsAdjustmentRequest_Cancel_Result

data CredentialBilling_AdjustBillingParams_Result

Result of adjusting the credential parameters.

CredentialBilling_AdjustBillingParams_Result

Field	Type	Description
newCredentialBillingCid	ContractId CredentialBilling	New credential billing with updated parameters.

data CredentialBilling_Bill_Result

Result of billing a credential.

CredentialBilling_Bill_Result

Field	Type	Description
billingCycleParams	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 FeeRecord)	Information on the CC fees burned as part of the transfer.

data CredentialBilling_Cancel_Result

Result of canceling a credential.

CredentialBilling_Cancel_Result

Field	Type	Description
canceledCredentialBillingCid	ContractId CanceledCredentialBilling	Canceled credential billing cid.

data CredentialBilling_DistributeAndAdjustDeposit_Result

Result of the CredentialBilling_DistributeAndAdjustDeposit choice.

CredentialBilling_DistributeAndAdjustDeposit_Result

Field	Type	Description
newCredentialBillingCid	ContractId CredentialBilling	New credential billing with updated deposit.
transferResult	TransferResult	Result of the coin transfer.

data CredentialBilling_Distribute_Result

Result of the CredentialBilling_Distribute choice.

CredentialBilling_Distribute_Result

Field	Type	Description
transferResult	TransferResult	Result of the coin transfer.

data CredentialBilling_RequestToAdjustBillingParams_Result

Result of the CredentialBilling_RequestToAdjustBillingParams choice.

CredentialBilling_RequestToAdjustBillingParams_Result

Field	Type	Description
requestCid	ContractId BillingParamsAdjustmentRequest

data CredentialBilling_TopUp_Result

Result of the CredentialBilling_TopUp choice.

CredentialBilling_TopUp_Result

Field	Type	Description
newCredentialBillingCid	ContractId CredentialBilling	New credential billing with updated deposit.

Functions

validateBalanceState

: BalanceState -> Update ()

Check that the balance state satisfies the accounting equations.

fetchAndValidateBillingContext

: Party -> Party -> AppTransferContext -> Update BillingContext

Fetch the billing context components from the ledger and validate them.

getDepositHoldingFees

: BillingContext -> ContractId LockedAmulet -> Update Decimal

Calculate the holding fees pending on the deposited LockedAmulet since its creation.

computeBillingCycleParams

: BillingContext -> BillingParams -> BillingState -> BillingCycleParams

Compute the billing parameters for the next billing cycle.

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.

executeDistribute

: CredentialBilling -> Decimal -> [ContractId Amulet] -> AppTransferContext -> Update CredentialBilling_Distribute_Result

Distribute coins to the credential holder.

executeTopUp

: CredentialBilling -> Decimal -> [ContractId Amulet] -> AppTransferContext -> Update CredentialBilling_TopUp_Result

Top up the deposit with an extra amount.

calculateNewBalanceState

: BillingCycleParams -> BalanceState -> 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).

cancelCredentialBilling

: CredentialBilling -> CredentialBilling_Cancel -> Update CredentialBilling_Cancel_Result

computeCcFees

: BillingContext -> Party -> [TransferOutput] -> Update Decimal

Compute the CC fees for a set of transfers.

unlockDeposit

: BillingContext -> ContractId LockedAmulet -> Update TransferInput

Unlock an existing deposit and return the coin as InputAmulet for a transfer.