Chainlet Billing

Chainlet Billing Overview

Chainlets are billed at a pre-determined interval depending on the type of chainlet it is and the duration of each epoch. Typically, a chainlet would be billed each day for the resources it consumes.

As each billing cycle is processed, the funds available to the chainlet inside the escrow account get depleted. Make sure you keep your escrow account funded to prevent your chainlet from being shutdown.

You can view how often a chainlet gets billed, and the corresponding billing amount, by looking up the type of chainlet you are running.

As an example, if your chainlet type is SagaOS, you can view the billing details by using sagacli

$ sagacli chainlet list-types
DisplayName     Description               Creator                                         Version     SetupCost          EpochCost              
-----------     -----------               -------                                         -------     ---------          ---------              
SagaOS          SagaOS Chainlet Stack     saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f     0.5.17       10000000upsaga     10000000upsaga/day

As you can see (slide to the right of the above code block), we have two separate costs associated with this chainlet type: a setup cost and an epoch cost.

A chainlet setup cost is a 1-time fee charged when the chainlet is initially launched.

An epoch cost is the amount billed at the end of each epoch. For SagaOS, the epoch is set to 1 day

As can be seen in our example listing above, we have a SetupCost of 10psaga (1 psaga = 1,000,000 upsaga) which is charged when the chainlet is launched.

We also have an EpochCost of 10psaga which is the amount billed to the chainlet each day.

All chainlets launched are charged a setup fee and a 30-day deposit of the epoch cost, which is then decremented as the chainlet gets billed each epoch.

For our example above, our chainlet launch cost would be

(SetupFee 10psaga) + (30 days * EpochCost 10psaga/day) = 310psaga.

This amount of 310psaga is charged to the chainlet launcher's wallet at chainlet launch, and deposited into the escrow account associated with the chainlet.

As the chainlet is billed each epoch, this escrow account gets depleted.

Ensure you have sufficient funds in the wallet launching the chainlet

Add funds to your chainlet at any time by depositing funds into the chainlet's escrow

View Billing History

As a user, you can view the billing history associated with any chainlet you have launched or contributed funds toward. To view the billing history of a chainlet, simply type:

sagacli account get-billing-history <chain-id>

Billing History Example

For example, to view the billing history of a chainlet with a chain-id of magicwarriors_1679599719-1:

$ sagacli account get-billing-history magicwarriors_1698795593524888-1
ChainletId                           ChainletName      ChainletOwner                                   BilledAmount       EpochIdentifier     EpochNumber     EpochStartTime
----------                           ------------      -------------                                   ------------       ---------------     -----------     --------------
magicwarriors_1698795593524888-1     magicwarriors     saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f     20000000upsaga     day                 1               2023-10-31T23:22:01Z

This output shows you the chainlet information along with the amount billed and the time the chainlet was billed.

This is a paginated query. Then, if you need to navigate through the chainlet billing history you have to change the value of --page and --limit flags.

Export all billing history

If for some reason you need to export all chainlet billing history in a single step, you can da that as well, just specifying the --csv-file flag:

$ sagacli account get-billing-history magicwarriors_1698795593524888-1 --csv-file /tmp/billing_history.csv

The csv file specified now contains all the billing history of magicwarriors_1679599719-1 chainlet recorded so far.

Further Details

To get further details and options associated with getting billing history, please refer to

sagacli account get-billing-history --help