Skip to content

Commit 795a0e7

Browse files
TjemmmicTjemmmic
authored
feat: pricing docs (#126)
* feat: pricing docs * fix: broken link
1 parent feb091c commit 795a0e7

File tree

6 files changed

+314
-10
lines changed

6 files changed

+314
-10
lines changed

‎pages/developers/blueprints/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { Meta } from "nextra";
33
const meta: Meta = {
44
introduction: "Introduction",
55
"use-cases": "Use Cases",
6+
"pricing-engine": "Pricing",
67
manager: "Blueprint Manager",
78
};
89

‎pages/developers/blueprints/pricing-engine.mdx

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
title: Blueprint Pricing
3+
---
4+
5+
# Blueprint Pricing
6+
7+
This guide explains how pricing works for blueprint execution and how to integrate pricing functionality into your applications that use Tangle Network blueprints.
8+
9+
## Prerequisites
10+
11+
- Understanding of Blueprint concepts and execution model
12+
- Familiarity with Tangle Network architecture
13+
- Basic knowledge of cryptographic signatures and verification
14+
15+
## Pricing Workflow
16+
17+
The complete workflow for getting quotes and executing blueprints consists of:
18+
19+
1. **Finding Operators**: Retrieve all operators registered for the blueprint to be executed.
20+
21+
2. **Requesting Quotes**: Request price quotes from operators:
22+
23+
- Generate a proof-of-work for the request
24+
- Create a properly formatted price request
25+
- Submit the request via gRPC (at the address specified by each operator on-chain)
26+
27+
3. **Processing Quotes**: When you receive quotes from operators:
28+
29+
- Verify their signatures
30+
- Validate the proof-of-work
31+
- Compare prices
32+
33+
4. **Selecting Operators**: Choose which operators to use based on their pricing quotes, typically selecting the most cost-effective options.
34+
35+
5. **Submitting Request**: Submit an on-chain request that includes your selected quotes via the `request_with_signed_price_quotes` services extrinsic.
36+
37+
6. **Blueprint Execution**: The selected operators will execute the blueprint according to the agreed terms.
38+
39+
## Pricing API
40+
41+
To request price quotes, your application will use the gRPC API provided by operators. You just need to send a `GetPrice` gRPC request to the operator's gRPC endpoint. Here's the service definition in protobuf:
42+
43+
```protobuf
44+
// The pricing service definition
45+
service Pricing {
46+
// Retrieves a signed price quote for a given blueprint
47+
rpc GetPrice (GetPriceRequest) returns (GetPriceResponse);
48+
}
49+
```
50+
51+
### Message Types
52+
53+
Here are the key message types you'll work with:
54+
55+
```protobuf
56+
// The pricing service definition
57+
service PricingEngine {
58+
// Retrieves a signed price quote for a given blueprint
59+
rpc GetPrice (GetPriceRequest) returns (GetPriceResponse);
60+
}
61+
62+
// Asset type enumeration
63+
enum AssetType {
64+
CUSTOM = 0;
65+
ERC20 = 1;
66+
}
67+
68+
// Asset type definition
69+
message Asset {
70+
oneof asset_type {
71+
// Custom asset with a numeric identifier
72+
uint64 custom = 1;
73+
// ERC20 token with an H160 address
74+
bytes erc20 = 2;
75+
}
76+
}
77+
78+
// Security requirements for an asset
79+
message AssetSecurityRequirements {
80+
// The asset type
81+
Asset asset = 1;
82+
// Minimum exposure percentage (0-100)
83+
uint32 minimum_exposure_percent = 2;
84+
// Maximum exposure percentage (0-100)
85+
uint32 maximum_exposure_percent = 3;
86+
}
87+
88+
// Security commitment for an asset
89+
message AssetSecurityCommitment {
90+
// The asset type
91+
Asset asset = 1;
92+
// Committed exposure percentage (0-100)
93+
uint32 exposure_percent = 2;
94+
}
95+
96+
// Resource requirement for a specific resource type
97+
message ResourceRequirement {
98+
// Resource kind (CPU, Memory, GPU, etc.)
99+
string kind = 1;
100+
// Quantity required
101+
uint64 count = 2;
102+
}
103+
104+
// Pricing for a specific resource type
105+
message ResourcePricing {
106+
// Resource kind (CPU, Memory, GPU, etc.)
107+
string kind = 1;
108+
// Quantity of the resource
109+
uint64 count = 2;
110+
// Price per unit in USD with decimal precision
111+
double price_per_unit_rate = 3;
112+
}
113+
114+
// Request message for GetPrice RPC
115+
message GetPriceRequest {
116+
// The blueprint ID
117+
uint64 blueprint_id = 1;
118+
// Time-to-live for service in blocks
119+
uint64 ttl_blocks = 2;
120+
// Proof of work to prevent DDOS
121+
bytes proof_of_work = 3;
122+
// Optional resource recommendations
123+
repeated ResourceRequirement resource_requirements = 4;
124+
// Security requirements for assets
125+
AssetSecurityRequirements security_requirements = 5;
126+
}
127+
128+
// Response message for GetPrice RPC
129+
message GetPriceResponse {
130+
// The quote details
131+
QuoteDetails quote_details = 1;
132+
// Signature of the hash of the body
133+
bytes signature = 2;
134+
// Operator ID
135+
bytes operator_id = 3;
136+
// Proof of work response
137+
bytes proof_of_work = 4;
138+
}
139+
140+
// The detailed quote information
141+
message QuoteDetails {
142+
// The blueprint ID
143+
uint64 blueprint_id = 1;
144+
// Time-to-live for service in blocks
145+
uint64 ttl_blocks = 2;
146+
// Total cost in USD with decimal precision
147+
double total_cost_rate = 3;
148+
// Timestamp when quote was generated
149+
uint64 timestamp = 4;
150+
// Expiry timestamp
151+
uint64 expiry = 5;
152+
// Resource pricing details
153+
repeated ResourcePricing resources = 6;
154+
// Security commitments for assets
155+
AssetSecurityCommitment security_commitments = 7;
156+
}
157+
```
158+
159+
## Implementation Steps
160+
161+
### 1. Generating Proof-of-Work
162+
163+
Before requesting a quote, you need to generate a valid proof-of-work for the request. The Operator pricing server uses the Equix Equihash Rust implementation for proof-of-work generation.
164+
165+
### 2. Creating and sending a Price Request
166+
167+
Next, create a price request with your requirements using the types defined in [Message Types](#message-types) and send it to each operator registered to the blueprint you want to run. Both the registered operators and their gRPC endpoints are available on-chain.
168+
169+
### 3. Verifying Quote Signatures
170+
171+
When you receive quotes, verify their authenticity by using the hash of the quote details and the operator's signature of the quote's hash that was included in the response.
172+
173+
### 4. Selecting Operators
174+
175+
After verifying the quotes, select the operators you want to use based on their pricing and security commitments. It is recommended to automatically select the lowest-priced operators.
176+
177+
### 5. Requesting service with quotes
178+
179+
After selecting the operators, submit your request to the blockchain using the `request_with_signed_price_quotes` services extrinsic with the selected operators and their quotes.
180+
181+
## Understanding Pricing Calculations
182+
183+
Operators calculate prices using this formula:
184+
185+
```
186+
Price = Resource Cost × Duration Factor × Security Factor
187+
```
188+
189+
This means that the total cost of a blueprint execution is the sum of the prices from all selected operators.
190+
191+
Where:
192+
193+
- **Resource Cost** = resource_count × price_per_unit_rate
194+
- **Duration Factor** = time_blocks × BLOCK_TIME
195+
- **Security Factor** = Factor based on security requirements
196+
197+
Understanding this helps you estimate costs and evaluate quotes effectively.
198+
199+
## Best Practices
200+
201+
1. **Get Multiple Quotes**: Always request quotes from all registered operators to compare prices
202+
2. **Verify All Signatures**: Always verify the signature of each quote before using it
203+
3. **Check Expiry Times**: Ensure quotes haven't expired before submitting them to the blockchain
204+
4. **Include Complete Security Requirements**: Specify all necessary security parameters in your requests
205+
5. **Handle Errors Gracefully**: Implement proper error handling for failed quote requests
206+
6. **Keep Quotes Intact**: Never modify quote details after receiving them
207+
7. **Use Fresh Proof-of-Work**: Generate a new proof-of-work for each request
208+
8. **Expect Price Variation**: Don't assume all operators will provide the same price

‎pages/developers/troubleshooting.mdx

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,7 @@ Caused by:
2727
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
2828
```
2929
30-
1. Verify your `gadget` version and compare your `rust_toolchain.toml` against the [Blueprint Template](https://github.com/tangle-network/blueprint-template) repository.
31-
32-
<GithubFileReaderDisplay
33-
url="https://github.com/tangle-network/blueprint-template/blob/main/rust-toolchain.toml"
34-
startLine={1}
35-
toLine={7}
36-
title="Blueprint Template rust_toolchain.toml"
37-
/>
38-
39-
2. Verify that your blueprint's jobs and reports are implemented correctly. Occasionally, our SDK may have breaking changes to the error reporting. You will want to consider commenting out metadata generation and then rebuilding to check for errors in the blueprint.
30+
Verify that your blueprint's jobs and reports are implemented correctly. Occasionally, our SDK may have breaking changes to the error reporting. You will want to consider commenting out metadata generation and then rebuilding to check for errors in the blueprint.
4031

4132
{/* TODO: Add URL */}
4233

‎pages/operators/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ const meta: Meta = {
1414
title: "Blueprint Operators",
1515
},
1616
operator: "Running an operator",
17+
pricing: "Pricing",
1718
"-- Eigenlayer AVS Operators": {
1819
type: "separator",
1920
title: "Eigenlayer AVS Operators",

‎pages/operators/pricing/_meta.ts

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import { Meta } from "nextra";
2+
3+
const meta: Meta = {
4+
overview: "Overview",
5+
};
6+
7+
export default meta;

‎pages/operators/pricing/overview.mdx

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Blueprint Pricing Overview
3+
---
4+
5+
# Blueprint Pricing
6+
7+
As a blueprint operator, you'll need to set up pricing for your services to receive fair compensation for the resources you provide. This guide explains how pricing works in the Tangle Network and how to configure it properly.
8+
9+
## Prerequisites
10+
11+
- Basic understanding of Tangle Network operations
12+
- Familiarity with running and maintaining a Tangle node
13+
- Knowledge of basic blueprint concepts
14+
15+
## How Blueprint Pricing Works
16+
17+
The pricing process follows these steps:
18+
19+
1. **Registration**: When you register as an operator for a blueprint, you provide your pricing service address in your preferences
20+
- **Note**: If your RPC server address changes, you can update it on-chain for any registered blueprint through the `updateRpcAddress` services extrinsic call
21+
2. **Quote Requests**: Users request price quotes from registered operators like you
22+
3. **Quote Generation**: Your service calculates prices based on resource requirements, creates security commitments, and signs quotes
23+
4. **Operator Selection**: Users select operators based on price and other factors
24+
5. **Service Execution**: Once selected, you'll begin execution of the blueprint and receive payment
25+
26+
## Setting Up Your Pricing Service
27+
28+
Your pricing service needs to be available via gRPC for users to request quotes. Here's how to configure it:
29+
30+
### Pricing Configuration
31+
32+
Create a TOML configuration file with your pricing structure. The file should include both default pricing for all blueprints and specific pricing for particular blueprints:
33+
34+
```toml
35+
# Default pricing for all blueprints
36+
[default]
37+
resources = [
38+
{ kind = "CPU", count = 1, price_per_unit_rate = 0.001 },
39+
{ kind = "MemoryMB", count = 1024, price_per_unit_rate = 0.00005 },
40+
{ kind = "StorageMB", count = 1024, price_per_unit_rate = 0.00002 },
41+
{ kind = "NetworkEgressMB", count = 1024, price_per_unit_rate = 0.00003 },
42+
{ kind = "NetworkIngressMB", count = 1024, price_per_unit_rate = 0.00001 },
43+
{ kind = "GPU", count = 1, price_per_unit_rate = 0.005 }
44+
]
45+
46+
# Blueprint-specific pricing (overrides default)
47+
[123] # Blueprint ID
48+
resources = [
49+
{ kind = "CPU", count = 1, price_per_unit_rate = 0.0012 },
50+
{ kind = "MemoryMB", count = 2048, price_per_unit_rate = 0.00006 },
51+
{ kind = "StorageMB", count = 1024, price_per_unit_rate = 0.00002 },
52+
{ kind = "NetworkEgressMB", count = 1024, price_per_unit_rate = 0.00003 },
53+
{ kind = "NetworkIngressMB", count = 1024, price_per_unit_rate = 0.00001 },
54+
{ kind = "GPU", count = 1, price_per_unit_rate = 0.005 }
55+
]
56+
```
57+
58+
Each resource type defines:
59+
60+
- `kind`: The resource type (CPU, MemoryMB, StorageMB, etc.)
61+
- `count`: The baseline quantity for the resource
62+
- `price_per_unit_rate`: The price per unit in USD with decimal precision, where it is generally the price per block for the resource
63+
64+
### How Prices Are Calculated
65+
66+
The formula used to calculate blueprint execution pricing is:
67+
68+
```
69+
Price = Resource Cost × Duration Factor × Security Factor
70+
```
71+
72+
Where:
73+
74+
- **Resource Cost** = resource_count × price_per_unit_rate
75+
- **Duration Factor** = time_blocks × BLOCK_TIME
76+
- **Security Factor** = Factor based on security commitment parameters
77+
78+
## Security Commitments
79+
80+
When users request your services, they include security requirements that specify what percentage of assets you need to secure. Your pricing service needs to respond with your commitment:
81+
82+
- **Exposure Percentage**: The percentage of assets you guarantee to secure (between the user's minimum and maximum requirements)
83+
- **Asset Types**: Can be Custom (u64) or ERC20 (H160 address)
84+
85+
This commitment will be included with your signed quote. The commitment used for the quote is automatically the minimum exposure percentage specified in the user's security requirements.
86+
87+
## Quote Security Considerations
88+
89+
### Quote Signature
90+
91+
- To ensure the validity of your quotes, your quotes are automatically signed. Users then verify the signature included in an Operator's quote when they receive it. This ensures a user is getting genuine quotes from you and other operators.
92+
93+
### Protection Against Abuse
94+
95+
- **Proof-of-Work Verification**: Users provide proof-of-work with their requests, defending against Denial-of-Service (DoS) attacks
96+
- **Quote Expiry**: Quotes include an expiry time (typically 10-15 minutes) to prevent stale quotes

0 commit comments

Comments
 (0)