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. This choice is disabled as of version 0.1.0 of this package.

  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). Deprecated, must be set to None.
  rewardReceiver	Optional Party	If set, we create an activity marker for this party as the beneficiary. This field is available starting from version 0.3.0 of this package.
  featuredAppRightCid	Optional (ContractId FeaturedAppRight)	The operator featured app right used to create the activity marker. This field is available starting from version 0.3.0 of this package.

• 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\_CancelExpired

  Cancels a credential billing where the locked deposit has expired. It is up to the issuer to revoke the associated credential upon billing cancelation.

  Controller: actor `oneOf` [issuer, holder, operator]

  Returns: CredentialBilling\_Cancel\_Result

  Field	Type	Description
  actor	Party	Party that initiated the cancellation.

• 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\_FlushExpiredDeposit

  Remove the deposit of a credential billing where the lock has expired. This choice was added as of version 0.4.0 of this package.

  Controller: actor `oneOf` [issuer, holder, operator]

  Returns: CredentialBilling\_FlushExpiredDeposit\_Result

  Field	Type	Description
  actor	Party	Party that initiates the flush.

• 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. No longer used.

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\_FlushExpiredDeposit\_Result

Result of the CredentialBilling_FlushExpiredDeposit choice.

CredentialBilling\_FlushExpiredDeposit\_Result

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

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.

computeBillingCycleParams

: BillingContext -> BillingParams -> BillingState -> BillingCycleParams

Compute the billing parameters for the next billing cycle.

executeBill

: CredentialBilling -> AppTransferContext -> Optional Party -> Optional (ContractId FeaturedAppRight) -> 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

cancelExpiredCredentialBilling

: CredentialBilling -> CredentialBilling\_CancelExpired -> Update CredentialBilling\_Cancel\_Result

flushExpiredCredentialBilling

: CredentialBilling -> Update CredentialBilling\_FlushExpiredDeposit\_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.