diff --git a/network/soroban-rpc/api-reference/methods/getFeeStats.mdx b/network/soroban-rpc/api-reference/methods/getFeeStats.mdx new file mode 100644 index 000000000..959af6630 --- /dev/null +++ b/network/soroban-rpc/api-reference/methods/getFeeStats.mdx @@ -0,0 +1,8 @@ +--- +hide_title: true +description: Returns statistics about charged inclusion fees for Soroban transactions and Stellar transactions +--- + +import { RpcMethod } from "@site/src/components/RpcMethod"; + + diff --git a/openrpc/src/methods/getFeeStats.json b/openrpc/src/methods/getFeeStats.json new file mode 100644 index 000000000..fd322c105 --- /dev/null +++ b/openrpc/src/methods/getFeeStats.json @@ -0,0 +1,79 @@ +{ + "name": "getFeeStats", + "summary": "returns statistics about charged inclusion fees", + "description": "Statistics for charged inclusion fees. The inclusion fee statistics are calculated from the inclusion fees that were paid for the transactions to be included onto the ledger. For Soroban transactions and Stellar transactions, they each have their own inclusion fees and own surge pricing. Inclusion fees are used to prevent spam and prioritize transactions during network traffic surge.", + "externalDocs": { + "url": "https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getFeeStats" + }, + "paramStructure": "by-name", + "params": [], + "result": { + "name": "getFeeStatsResult", + "schema": { + "type": "object", + "properties": { + "sorobanInclusionFee": { + "description": "Inclusion fee distribution statistics for Soroban transactions", + "$ref": "#/components/schemas/FeeDistribution" + }, + "inclusionFee": { + "description": "Fee distribution statistics for Stellar (i.e. non-Soroban) transactions. Statistics are normalized per operation.", + "$ref": "#/components/schemas/FeeDistribution" + }, + "latestLedger": { + "$ref": "#/components/schemas/LatestLedger" + } + } + } + }, + "examples": [ + { + "name": "Statistics about charged transaction fees.", + "description": "Example request to the `getFeeStats` method", + "params": [], + "result": { + "name": "getFeeStatsResult", + "value": { + "sorobanInclusionFee": { + "max": "210", + "min": "100", + "mode": "100", + "p10": "100", + "p20": "100", + "p30": "100", + "p40": "100", + "p50": "100", + "p60": "100", + "p70": "100", + "p80": "100", + "p90": "120", + "p95": "190", + "p99": "200", + "transactionCount": "10", + "ledgerCount": 50 + }, + "inclusionFee": { + "max": "100", + "min": "100", + "mode": "100", + "p10": "100", + "p20": "100", + "p30": "100", + "p40": "100", + "p50": "100", + "p60": "100", + "p70": "100", + "p80": "100", + "p90": "100", + "p95": "100", + "p99": "100", + "transactionCount": "7", + "ledgerCount": 10 + }, + "latestLedger": 4519945 + } + + } + } + ] +} diff --git a/openrpc/src/schemas/FeeDistribution.json b/openrpc/src/schemas/FeeDistribution.json new file mode 100644 index 000000000..7c7fffdfe --- /dev/null +++ b/openrpc/src/schemas/FeeDistribution.json @@ -0,0 +1,67 @@ +{ + "FeeDistribution": { + "type": "object", + "properties": { + "max": { + "description": "Maximum fee", + "type": "string" + }, + "min": { + "description": "Minimum fee", + "type": "string" + }, + "mode": { + "description": "Fee value which occurs the most often", + "type": "string" + }, + "p10": { + "description": "10th nearest-rank fee percentile", + "type": "string" + }, + "p20": { + "description": "20th nearest-rank fee percentile", + "type": "string" + }, + "p30": { + "description": "30th nearest-rank fee percentile", + "type": "string" + }, + "p40": { + "description": "40th nearest-rank fee percentile", + "type": "string" + }, + "p50": { + "description": "50th nearest-rank fee percentile", + "type": "string" + }, + "p60": { + "description": "60th nearest-rank fee percentile", + "type": "string" + }, + "p70": { + "description": "70th nearest-rank fee percentile", + "type": "string" + }, + "p80": { + "description": "80th nearest-rank fee percentile", + "type": "string" + }, + "p90": { + "description": "90th nearest-rank fee percentile.", + "type": "string" + }, + "p99": { + "description": "99th nearest-rank fee percentile", + "type": "string" + }, + "transactionCount": { + "description": "How many transactions are part of the distribution", + "type": "number" + }, + "ledgerCount": { + "description": "How many consecutive ledgers form the distribution", + "type": "number" + } + } + } +} diff --git a/static/openrpc.json b/static/openrpc.json index 3ae501e2b..62ae42f04 100644 --- a/static/openrpc.json +++ b/static/openrpc.json @@ -334,6 +334,210 @@ } ] }, + { + "name": "getFeeStats", + "summary": "returns statistics about charged inclusion fees", + "description": "Statistics for charged inclusion fees. The inclusion fee statistics are calculated from the inclusion fees that were paid for the transactions to be included onto the ledger. For Soroban transactions and Stellar transactions, they each have their own inclusion fees and own surge pricing. Inclusion fees are used to prevent spam and prioritize transactions during network traffic surge.", + "externalDocs": { + "url": "https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getFeeStats" + }, + "paramStructure": "by-name", + "params": [], + "result": { + "name": "getFeeStatsResult", + "schema": { + "type": "object", + "properties": { + "sorobanInclusionFee": { + "type": "object", + "description": "Inclusion fee distribution statistics for Soroban transactions", + "properties": { + "max": { + "description": "Maximum fee", + "type": "string" + }, + "min": { + "description": "Minimum fee", + "type": "string" + }, + "mode": { + "description": "Fee value which occurs the most often", + "type": "string" + }, + "p10": { + "description": "10th nearest-rank fee percentile", + "type": "string" + }, + "p20": { + "description": "20th nearest-rank fee percentile", + "type": "string" + }, + "p30": { + "description": "30th nearest-rank fee percentile", + "type": "string" + }, + "p40": { + "description": "40th nearest-rank fee percentile", + "type": "string" + }, + "p50": { + "description": "50th nearest-rank fee percentile", + "type": "string" + }, + "p60": { + "description": "60th nearest-rank fee percentile", + "type": "string" + }, + "p70": { + "description": "70th nearest-rank fee percentile", + "type": "string" + }, + "p80": { + "description": "80th nearest-rank fee percentile", + "type": "string" + }, + "p90": { + "description": "90th nearest-rank fee percentile.", + "type": "string" + }, + "p99": { + "description": "99th nearest-rank fee percentile", + "type": "string" + }, + "transactionCount": { + "description": "How many transactions are part of the distribution", + "type": "number" + }, + "ledgerCount": { + "description": "How many consecutive ledgers form the distribution", + "type": "number" + } + } + }, + "inclusionFee": { + "type": "object", + "description": "Fee distribution statistics for Stellar (i.e. non-Soroban) transactions. Statistics are normalized per operation.", + "properties": { + "max": { + "description": "Maximum fee", + "type": "string" + }, + "min": { + "description": "Minimum fee", + "type": "string" + }, + "mode": { + "description": "Fee value which occurs the most often", + "type": "string" + }, + "p10": { + "description": "10th nearest-rank fee percentile", + "type": "string" + }, + "p20": { + "description": "20th nearest-rank fee percentile", + "type": "string" + }, + "p30": { + "description": "30th nearest-rank fee percentile", + "type": "string" + }, + "p40": { + "description": "40th nearest-rank fee percentile", + "type": "string" + }, + "p50": { + "description": "50th nearest-rank fee percentile", + "type": "string" + }, + "p60": { + "description": "60th nearest-rank fee percentile", + "type": "string" + }, + "p70": { + "description": "70th nearest-rank fee percentile", + "type": "string" + }, + "p80": { + "description": "80th nearest-rank fee percentile", + "type": "string" + }, + "p90": { + "description": "90th nearest-rank fee percentile.", + "type": "string" + }, + "p99": { + "description": "99th nearest-rank fee percentile", + "type": "string" + }, + "transactionCount": { + "description": "How many transactions are part of the distribution", + "type": "number" + }, + "ledgerCount": { + "description": "How many consecutive ledgers form the distribution", + "type": "number" + } + } + }, + "latestLedger": { + "title": "latestLedger", + "description": "The sequence number of the latest ledger known to Soroban RPC at the time it handled the request.", + "type": "number" + } + } + } + }, + "examples": [ + { + "name": "Statistics about charged transaction fees.", + "description": "Example request to the `getFeeStats` method", + "params": [], + "result": { + "name": "getFeeStatsResult", + "value": { + "sorobanInclusionFee": { + "max": "210", + "min": "100", + "mode": "100", + "p10": "100", + "p20": "100", + "p30": "100", + "p40": "100", + "p50": "100", + "p60": "100", + "p70": "100", + "p80": "100", + "p90": "120", + "p95": "190", + "p99": "200", + "transactionCount": "10", + "ledgerCount": 50 + }, + "inclusionFee": { + "max": "100", + "min": "100", + "mode": "100", + "p10": "100", + "p20": "100", + "p30": "100", + "p40": "100", + "p50": "100", + "p60": "100", + "p70": "100", + "p80": "100", + "p90": "100", + "p95": "100", + "p99": "100", + "transactionCount": "7", + "ledgerCount": 10 + }, + "latestLedger": 4519945 + } + } + } + ] + }, { "name": "getHealth", "summary": "returns node health",