Merge pull request #2297 from dfinity/update-gas-cost

Overhaul Gas & Cycles cost page

docs/concepts/tokens-cycles.md

@@ -1,4 +1,4 @@
-# Tokens and cycles
+# ICP tokens
 
 ## Overview 
 Internet Computer Protocol tokens (ICP tokens) are a native utility token with a value determined on the open market. ICP tokens play a key role in both the governance and the economics of the Internet Computer.
@@ -28,27 +28,17 @@ As this diagram suggests, how you use ICP tokens depends primarily on your goals
 Regarding transaction fees, the **transaction sender** is responsible for covering any/all transaction fees.
 :::
 
-## How cycles work
+## Cycles
 
-For developers, ICP tokens are important because they can be converted to cycles that, in turn, are used to pay for resource consumption.
+Cycles are burned by canisters to pay for the resources they consume such as execution, storage, and messaging. Cycles have a fixed price where 1 trillion cycles is equal to 1 XDR, an official group of currencies maintained by [IMF](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx). This means that running costs of canisters are decoupled from price fluctuations of ICP.
 
-As an example, imagine you have a house where propane is used for a water heater, kitchen stove, dryer, and space heater. As you use these appliances, you deplete the supply of gas you have on hand, so periodically you contact a provider to refill your supply so you can continue to use your appliances without interruption. This is similar to canisters in that each canister must have an account with cycles available to pay for the communication, computation, and storage that the canister’s application consumes.
-
-To learn more about cycles and how to use them, see [here](/docs/developer-docs/setup/cycles/converting_icp_tokens_into_cycles.md).
-
-## Cost of computation
-
-Cycles reflect the real costs of operations for applications hosted in the Internet Computer blockchain including resources such physical hardware, rack space, energy, storage devices, and bandwidth.
+For developers, ICP tokens are important because they can be converted to cycles that, in turn, are used to pay for resource consumption. Cycles reflect the real costs of operations for applications hosted in the Internet Computer blockchain including resources such physical hardware, rack space, energy, storage devices, and bandwidth.
 
 Canister smart contracts must be able to pay for complete execution (all or nothing), but the platform sets limits on how many cycles a canister can hold and consume to prevent malicious code from draining resources.
 
-The relative stability of operational costs makes it easier to predict the cycles required to process, for example, a million messages.
-
-The costs associated with communication, computation, and storage are more likely to decrease than to increase over time. For example, because disk space becomes cheaper and hardware becomes more efficient, the Internet Computer protocol will also improve over time to make better use of the resources.
-
-Cycles are not a currency; in particular cycles cannot be converted back to value in the form of Internet Computer Protocol tokens, but can be transferred between canisters to enable canisters to pay for operations.
+To learn more about cycles and how to use them, see [here](/docs/developer-docs/setup/cycles/converting_icp_tokens_into_cycles.md).
 
-For exact costs see the tables in [computation and storage costs](/developer-docs/gas-cost.md).
+For more information on cycles costs, see the tables in [computation and storage costs](/developer-docs/gas-cost.md).
 
 ## Token value and volatility
 

docs/developer-docs/cost-estimations-and-examples.md

@@ -0,0 +1,170 @@
+# Cycles cost estimations and examples
+
+
+## Overview
+
+To get a rough estimate of how much your project may cost, below are a few common project architectures and their estimated monthly cost in cycles. These estimates are broken down into the following  groups:
+
+
+- **Messaging**: A message transmission refers to calls that are made to a canister's methods. Messaging costs depend on the type of call being sent (query, update, inter-canister, etc), the size of the message's request and response bytes, and the total amount of messages a canister sends and receives.
+
+- **Execution**: This refers to cycles charged during execution of message and tasks. There is a fixed fee for starting execution and fee per each executed instruction.
+
+- **Storage**: This refers to cycles charged for canister storage. Note that it includes both the Wasm memory and the stable memory.
+
+- **Special features**: Special feature transmissions include HTTPS outcalls, transmissions using the [Bitcoin API](./integrations/bitcoin/bitcoin-how-it-works.md), and transmissions using the [chain-key signing API](./integrations/t-ecdsa/t-ecdsa-how-it-works.md).
+
+## Units and fiat value
+
+The price of cycles is fixed against the price of [XDR](/docs/current/references/glossary#xdr), where **1 trillion cycles equals 1 XDR**.
+
+This documentation will use the following units to measure and calculate the number of cycles and their associated fiat value:
+
+
+| Abbr. | Name | In numbers | Cycles XDR value | Cycles USD value |
+|-------|------|------------|------------------|------------------|
+| T | Trillion | 1_000_000_000_000 | 1 | 1.34 |
+| B | Billion | 1_000_000_000 | 0.001 | 0.00134 |
+| M | Million | 1_000_000 | 0.000001 | 0.00000134 |
+| k | Thousand | 1_000 | 0.000000001 | 0.00000000134 |
+| – | (one) | 1 | 0.000000000001 | 0.00000000000134|
+
+## Estimated cost of sample project architectures
+
+:::caution
+The estimates below are simply to demonstrate what different sample architectures may cost. The actual cost of your project will vary based on the exact number of resources and canister calls that are used. Therefore, the estimates below should only be used for gaining an idea of what a project may cost but should not be used for budgeting exact costs. For exact costs, you can calculate them using the chart here: [Cycles and transmission costs](gas-cost.md).
+:::
+
+:::info
+These estimates use a 13-node subnet. Costs will be different if deployed on a 34-node subnet. Please refer to the chart here for more details: [Cycles and transmission costs](gas-cost.md).
+:::
+
+
+### Single canister
+
+The following is the cost estimate for a single canister that provides a service or function that is used by 5 users that each stores 100KB of data, is called by other canisters through inter-canister calls, and stores 5GB of data. The average number of request and response bytes per message is 351, and the number of instructions executed per message is 1_000_000, with 100 daily messages generated per user per day. This canister also performs 50 daily tasks, with 1_000_000 instructions executed per task. This project does not use HTTPS outcalls or other special features.
+
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 19B | $0.03 USD | 228B | $0.36 USD |
+| Execution | 25.2B | $0.03 USD | 302.4B | $0.36 USD |
+| Storage | 1.53T | $2.05 USD | 18.36T | $24.60 USD |
+| HTTPS outcalls | 0 | $0 USD | 0 | $0 USD |
+
+
+### Simple static website using a frontend canister
+
+The following is the cost estimate for a simple static website that uses a single frontend canister for the website's assets that is not called by other canisters or performs HTTPS outcalls. It stores 5GB of data, has 100 total users, and has 10 daily active users that each generate 50 messages per day. The average number of request and response bytes per message is 351, and the number of instructions executed per message is 1_000_000. This project does not use HTTPS outcalls or other special features.
+
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 1.06B | $0.01 USD | 12.72B | $0.12 USD |
+| Execution | 1.65B | $0.02 USD | 19.8B | $0.24 USD |
+| Storage | 1.53T | $2.05 USD | 18.36T | $24.60 USD |
+| HTTPS outcalls | 0 | $0 USD | 0 | $0 USD |
+
+
+:::caution
+When considering developing a website on ICP, the estimated cost above might appear higher than the 'free tier' of a traditional Web2 service. However, there are several important benefits to consider that traditional Web2 web hosting services often hold behind additional paywalls, such as:
+
+
+- Fees for multiple developers.
+
+- Fees for access to workflows that use third-party services such as Github or Gitlab.
+
+- Fees to enable advanced frontend functionality, like developing submittable forms, certain web assets, or streaming content.
+
+- Fees to view site analysis.
+
+- Fees to upload large media files.
+
+- Fees for advanced security functions or features.
+
+On ICP, the fees broken down in this document are the only fees that are charged for developing. Developers only pay for exactly what is used by their project's canisters in terms of resources, and no features are restricted behind additional paywalls. Developers can integrate any aspect of ICP into their dapp (such as Internet Identity or chain-key cryptography) without being charged additional fees. Development teams can exist of any size, use any workflow they desire, and do not have to worry about fitting within certain resource limits to stay under a certain paid tier.
+:::
+
+
+### Simple smart contract web dapp using a frontend canister and backend canister
+
+The following is the cost estimate for a simple smart contract-powered web dapp that uses two canisters: a backend canister for the dapp's functionality and a frontend canister for the user interface. This dapp has 100 users, 10 of whom are daily active users that generate 1_000 messages per day. The average number of request and response bytes per message is 245, and the number of instructions executed per message is 1_442_185. The dapp stores 100KB of data per user and stores 10GB of user-independent data. This project does not use HTTPS outcalls or other special features.
+
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 901B | $1.21 USD | 1.0812T | $14.52 USD |
+| Execution | 1.34T | $1.79 USD | 16.08T | $21.48 USD |
+| Storage | 3.07T | $4.11 USD | 36.84T | $49.32 USD |
+| HTTPS outcalls | 0 | $0 USD | 0 | $0 USD |
+
+
+### Social media dapp with two canisters
+
+The following is the cost estimate for a project that creates a social media dapp using two canisters with 200 user accounts, 50 of which are active daily and generate 6_127 messages per day. The average number of request and response bytes per message is 245, and the number of instructions executed per message is 1_442_185. This project also uses 2000 HTTPS outcalls per day, with an average of 250 request and response bytes per outcall. Furthermore, the project stores 100KB of data per user and 25GB of user-independent storage.
+
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 25.7T | $34.38 USD | 308.4T | $412.56 USD |
+| Execution | 3.79T | $50.74 USD | 45.48T | $608.88 USD |
+| Storage | 7.67T | $10.28 USD | 92.04T | $123.36 USD |
+| HTTPS outcalls | 3.18T | $4.26 USD | 38.16T | $51.12 USD |
+
+
+### Decentralized service using threshold ECDSA and HTTPS outcalls
+
+The following is the cost estimate for a project that creates a decentralized service with 5_000 users, 100 of whom are active daily and generate 4_400 messages per day. The average number of request and response bytes per message is 500, and the number of instructions executed per message is 437_253. This project also uses 3691 HTTPS outcalls per day, with an average of 332 request and response bytes per outcall. Furthermore, the project stores 100KB of data per user and 150GB of user-independent storage.
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 198T | $265.36 USD | 2_376T | $3_184.32 USD |
+| Execution | 402T | $538.90 USD | 4_824T | $6_466.80 USD |
+| Storage | 46.1T | $61.83 USD | 553.2T | $741.96 USD |
+| HTTPS outcalls | 6.01T | $8.06 USD | 72.12T | $96.72 USD |
+
+:::caution
+This example resembles that of an enterprise-level project that expects the application will make about 1500 HTTPS outcalls per day. For reference, the [Orally](https://orally.network/) enterprise application on ICP averages between 35_000 and 46_000 HTTPS outcalls per month.
+
+An enterprise-level project of this size could potentially cost several thousands of dollars if deployed on a traditional Web2 platform. Web2 infrastructure services often charge additional fees that scale with the number of requests that your project serves per day or per month. Traditional Web2 infrastructure services also frequently charge high fees for additional features or 'add-ons' to your application. Such fees do not exist on ICP; the fees listed in this document are the only fees associated with developing on ICP. Therefore, it is possible to run large enterprise applications on ICP at a fraction of what the cost would be if deploying on a Web2 service.
+:::
+
+
+### Instant messaging dapp with thousands of canisters
+
+The following is the cost estimate for a project that creates a messaging dapp where each user's data is stored in its own canister with 15_000 total users. 1_500 of these users are active daily, generating 5_700 messages each per day. The average number of request and response bytes per message is 624, and the number of instructions executed per message is 74_983. This project does not use HTTPS outcalls or other special features. Furthermore, the project stores 10MB of data per user and 750GB of user-independent storage.
+
+
+| Transaction group | Cost per month in cycles | Cost per month in USD | Cost per year in cycles | Cost per year in USD |
+| ----------------- | ------------------------ | --------------------- | ----------------------- | -------------------- |
+| Messaging | 464T | $622.12 USD | 5_568T | $7_465.44 USD |
+| Execution | 382T | $511.89 USD | 4_584T | $6_142.68 USD |
+| Storage | 276T | $369.73 USD | 3_312T | $4_436.76 USD |
+| HTTPS outcalls | 0 | $0.00 USD | 0 | $0.00 USD |
+
+:::caution
+In this example, a new canister is created for each user. That means, each time a new user signs up for the dapp, a cost of 100_000_000_000 is charged. This additional cost should be considered when choosing an architecture similar to this, as it can become expensive quickly.
+:::
+
+## How is the number of cycles charged to a canister estimated?
+
+The number of cycles charged to the canister can be estimated using the following parameters:
+
+- Nodes in the subnet the canister is deployed to: If deployed locally, this number is 1. If deployed on the mainnet, this number is either 13 or 34.
+- Amount of users: The total number of users that interact with the canister.
+- Daily active users: The total number of users that interact with the canister daily.
+- Daily messages per active user: The total number of messages sent to the canister that each active user generates.
+- Request and response bytes per message: The size of the request and response bytes per message.
+- Instructions executed per message: The number of instructions that are executed in response to each message.
+- Calls per message: The number of calls that are triggered per message.
+- Request and response bytes per call: The size of the request and response bytes per call.
+- Instructions per call: The number of instructions that are executed per call.
+- Daily tasks: The number of daily tasks that the canister executes.
+- Instructions executed per task: The number of instructions that are executed per daily task.
+- Daily HTTPS outcalls: The number of daily HTTPS outcalls the canister makes.
+- Request bytes per HTTPS outcall: The size of the request bytes per HTTPS outcall.
+- Response bytes per HTTPS outcall: The size of the response bytes per HTTPS outcall.
+- Storage bytes per user: The amount of data that is stored for each user.
+- User-independent storage bytes: The amount of data the canister stores, independent of the storage used per user.
+
+HTTPS outcalls are a special feature that is calculated differently than the other resources. Additionally, if a canister uses the [Bitcoin API](./integrations/bitcoin/bitcoin-how-it-works.md) or makes transmissions using the [chain-key signing API](./integrations/t-ecdsa/t-ecdsa-how-it-works.md), there are additional cycle costs for these special feature transmissions.