From aaa0d764d0ae48ddd1195601e1f7886012c610e3 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:11:18 +1000 Subject: [PATCH 1/7] add rpc migration guide to documentation --- docs/data/migrate-from-horizon-to-rpc.mdx | 107 ++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/data/migrate-from-horizon-to-rpc.mdx diff --git a/docs/data/migrate-from-horizon-to-rpc.mdx b/docs/data/migrate-from-horizon-to-rpc.mdx new file mode 100644 index 000000000..774df45fd --- /dev/null +++ b/docs/data/migrate-from-horizon-to-rpc.mdx @@ -0,0 +1,107 @@ +--- +title: Migrate from Horizon to RPC +sidebar_position: 0 +hide_table_of_contents: true +--- + +When migrating from [Horizon] to [RPC], applications using [Horizon's REST API] will need to be updated to use the [RPC JSON-RPC API]. This guide provides an overview of the key differences between the two APIs and how to migrate your application. + +| Horizon Endpoint | RPC Method | +|------------------|------------| +| [`GET /`] | [`getLatestLedger`] [`getVersionInfo`] [`getHealth`] [`getNetwork`] | +| [`GET /ledgers`] | [`getLedgers`] | +| [`GET /ledgers/{seq}`] | [`getLedgers`] | +| [`GET /ledgers/{seq}/transactions`] | [`getTransactions`] | +| [`GET /ledgers/{seq}/operations`] | [`getTransactions`] | +| [`GET /ledgers/{seq}/payments`] | [`getEvents`]\* | +| [`GET /ledgers/{seq}/effects`] | [`getEvents`]\* | +| [`POST /transactions`] | [`sendTransaction`] | +| [`POST /transactions_async`] | [`sendTransaction`] | +| [`GET /transactions`] | [`getTransactions`] | +| [`GET /transactions/{hash}`] | [`getTransaction`] | +| [`GET /transactions/{hash}/operations`] | [`getTransaction`] | +| [`GET /transactions/{hash}/payments`] | - | +| [`GET /transactions/{hash}/effects`] | - | +| [`GET /operations`] | [`getTransactions`] | +| [`GET /operations/{id}`] | - | +| [`GET /operations/{id}/effects`] | - | +| [`GET /fee_stats`] | [`getFeeStats`] [`simulateTransaction`] | +| [`GET /accounts`] | - | +| [`GET /accounts/{address}`] | [`getLedgerEntries`] | +| [`GET /claimable_balances`] | - | +| [`GET /claimable_balances/{id}`] | [`getLedgerEntries`] | +| [`GET /claimable_balances/{id}/transactions`] | - | +| [`GET /claimable_balances/{id}/operations`] | - | +| [`GET /liquidity_pools`] | - | +| [`GET /liquidity_pools/{id}`] | [`getLedgerEntries`] | +| [`GET /liquidity_pools/{id}/transactions`] | - | +| [`GET /liquidity_pools/{id}/operations`] | - | +| [`GET /liquidity_pools/{id}/effects`] | - | +| [`GET /liquidity_pools/{id}/trades`] | - | +| [`GET /offers`] | - | +| [`GET /offers/{id}`] | [`getLedgerEntries`] | +| [`GET /offers/{id}/trades`] | - | +| [`GET /payments`] | [`getEvents`]\* | +| [`GET /effects`] | [`getEvents`]\* | +| [`GET /trades`] | [`getEvents`]\* | + +\* The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. + +\- The RPC API does not have a direct replacement for endpoints marked with a dash. To build similar functionality in an application, take a look at other [Data] products. + +[CAP-67]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md +[Horizon]: horizon +[RPC]: rpc +[Horizon's REST API]: horizon/api-reference +[RPC JSON-RPC API]: rpc/api-reference +[Data]: ../data + +[`GET /`]: horizon/api-reference +[`GET /ledgers`]: horizon/api-reference/list-all-ledgers +[`GET /ledgers/{seq}`]: horizon/api-reference/retrieve-a-ledger +[`GET /ledgers/{seq}/transactions`]: horizon/api-reference/retrieve-a-ledgers-transactions +[`GET /ledgers/{seq}/operations`]: horizon/api-reference/retrieve-a-ledgers-operations +[`GET /ledgers/{seq}/payments`]: horizon/api-reference/retrieve-a-ledgers-payments +[`GET /ledgers/{seq}/effects`]: horizon/api-reference/retrieve-a-ledgers-effects +[`POST /transactions`]: horizon/api-reference/submit-a-transaction +[`POST /transactions_async`]: horizon/api-reference/submit-async-transaction +[`GET /transactions`]: horizon/api-reference/list-all-transactions +[`GET /transactions/{hash}`]: horizon/api-reference/retrieve-a-transaction +[`GET /transactions/{hash}/operations`]: horizon/api-reference/retrieve-a-transactions-operations +[`GET /transactions/{hash}/payments`]: horizon/api-reference/retrieve-a-transactions-payments +[`GET /transactions/{hash}/effects`]: horizon/api-reference/retrieve-a-transactions-effects +[`GET /operations`]: horizon/api-reference/list-all-operations +[`GET /operations/{id}`]: horizon/api-reference/retrieve-an-operation +[`GET /operations/{id}/effects`]: horizon/api-reference/retrieve-an-operations-effects +[`GET /fee_stats`]: horizon/api-reference +[`GET /accounts`]: horizon/api-reference/list-all-accounts +[`GET /accounts/{address}`]: horizon/api-reference/retrieve-an-account +[`GET /claimable_balances`]: horizon/api-reference/list-all-claimable-balances +[`GET /claimable_balances/{id}`]: horizon/api-reference/retrieve-a-claimable-balance +[`GET /claimable_balances/{id}/transactions`]: horizon/api-reference/cb-retrieve-related-transactions +[`GET /claimable_balances/{id}/operations`]: horizon/api-reference/cb-retrieve-related-operations +[`GET /liquidity_pools`]: horizon/api-reference/list-liquidity-pools +[`GET /liquidity_pools/{id}`]: horizon/api-reference/retrieve-a-liquidity-pool +[`GET /liquidity_pools/{id}/transactions`]: horizon/api-reference/lp-retrieve-related-transactions +[`GET /liquidity_pools/{id}/operations`]: horizon/api-reference/lp-retrieve-related-operations +[`GET /liquidity_pools/{id}/effects`]: horizon/api-reference/retrieve-related-effects +[`GET /liquidity_pools/{id}/trades`]: horizon/api-reference/retrieve-related-trades +[`GET /offers`]: horizon/api-reference/get-all-offers +[`GET /offers/{id}`]: horizon/api-reference/get-offer-by-offer-id +[`GET /offers/{id}/trades`]: horizon/api-reference/get-trades-by-offer-id +[`GET /payments`]: horizon/api-reference/list-all-payments +[`GET /effects`]: horizon/api-reference/list-all-effects +[`GET /trades`]: horizon/api-reference/get-all-trades + +[`getLatestLedger`]: rpc/api-reference/methods/getLatestLedger +[`getVersionInfo`]: rpc/api-reference/methods/getVersionInfo +[`getHealth`]: rpc/api-reference/methods/getHealth +[`getNetwork`]: rpc/api-reference/methods/getNetwork +[`getLedgers`]: rpc/api-reference/methods/getLedgers +[`getTransactions`]: rpc/api-reference/methods/getTransactions +[`getTransaction`]: rpc/api-reference/methods/getTransaction +[`getEvents`]: rpc/api-reference/methods/getEvents +[`sendTransaction`]: rpc/api-reference/methods/sendTransaction +[`getFeeStats`]: rpc/api-reference/methods/getFeeStats +[`simulateTransaction`]: rpc/api-reference/methods/simulateTransaction +[`getLedgerEntries`]: rpc/api-reference/methods/getLedgerEntries From 1d5db1632d0dcb8f8a8229f75260018f7ea2a97b Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 12:13:06 +1000 Subject: [PATCH 2/7] add migration guide to data sidebar --- config/sidebars.ts | 6 ++++++ docusaurus.config.ts | 10 ++++++++++ 2 files changed, 16 insertions(+) diff --git a/config/sidebars.ts b/config/sidebars.ts index bef8dd772..ed29a2497 100644 --- a/config/sidebars.ts +++ b/config/sidebars.ts @@ -29,6 +29,12 @@ const sidebars: SidebarsConfig = { { type: 'ref', id: 'data/galexie/README', label: 'Galexie'}, { type: 'ref', id: 'data/data-indexers/README', label: 'Data Indexers'}, { type: 'ref', id: 'data/oracles/README', label: 'Oracles'}, + { type: 'html', value: 'Migration Guides', defaultStyle: true, className: 'networkMenuHtmlItem'}, + { + type: "ref", + id: "data/migrate-from-horizon-to-rpc", + label: "Horizon to RPC" + }, ], tools: [ { diff --git a/docusaurus.config.ts b/docusaurus.config.ts index e492da66e..edde1f935 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -184,6 +184,16 @@ const config: Config = { type: 'doc', docId: "data/oracles/README", label: "Oracles", + }, + { + type: 'html', + value: '
Migration Guides', + className: 'subtitle', + }, + { + type: 'doc', + docId: 'data/migrate-from-horizon-to-rpc', + label: 'Horizon to RPC' } ] }, From 790d948c03e16c97225873dbfdd61225040d48a5 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 12:27:19 +1000 Subject: [PATCH 3/7] menu --- config/sidebars.ts | 4 ++-- .../README.mdx} | 0 docusaurus.config.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename docs/data/{migrate-from-horizon-to-rpc.mdx => migrate-from-horizon-to-rpc/README.mdx} (100%) diff --git a/config/sidebars.ts b/config/sidebars.ts index ed29a2497..6c02d4f81 100644 --- a/config/sidebars.ts +++ b/config/sidebars.ts @@ -31,8 +31,8 @@ const sidebars: SidebarsConfig = { { type: 'ref', id: 'data/oracles/README', label: 'Oracles'}, { type: 'html', value: 'Migration Guides', defaultStyle: true, className: 'networkMenuHtmlItem'}, { - type: "ref", - id: "data/migrate-from-horizon-to-rpc", + type: "doc", + id: "data/migrate-from-horizon-to-rpc/README", label: "Horizon to RPC" }, ], diff --git a/docs/data/migrate-from-horizon-to-rpc.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx similarity index 100% rename from docs/data/migrate-from-horizon-to-rpc.mdx rename to docs/data/migrate-from-horizon-to-rpc/README.mdx diff --git a/docusaurus.config.ts b/docusaurus.config.ts index edde1f935..83a144cf0 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -192,7 +192,7 @@ const config: Config = { }, { type: 'doc', - docId: 'data/migrate-from-horizon-to-rpc', + docId: 'data/migrate-from-horizon-to-rpc/README', label: 'Horizon to RPC' } ] From 1697a73d7c7645a89669fed0eb4c06deb312eb65 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 13:08:57 +1000 Subject: [PATCH 4/7] add more words' --- .../migrate-from-horizon-to-rpc/README.mdx | 37 +++++++++++++------ 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/data/migrate-from-horizon-to-rpc/README.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx index 774df45fd..90e6de34c 100644 --- a/docs/data/migrate-from-horizon-to-rpc/README.mdx +++ b/docs/data/migrate-from-horizon-to-rpc/README.mdx @@ -1,10 +1,23 @@ --- title: Migrate from Horizon to RPC sidebar_position: 0 -hide_table_of_contents: true --- -When migrating from [Horizon] to [RPC], applications using [Horizon's REST API] will need to be updated to use the [RPC JSON-RPC API]. This guide provides an overview of the key differences between the two APIs and how to migrate your application. +Applications using [Horizon's REST-like API] will need to be updated to use the [RPC JSON-RPC API] when migrating from [Horizon] to [RPC]. This guide provides an overview of the key differences between the two APIs and how to migrate your application. + +## Request / Response Format + +Horizon's REST-like API uses HTTP methods and status codes to communicate with clients. Responses are JSON in the HAL format. See [Horizon's Response Format]. + +RPC's JSON-RPC API uses JSON-RPC 2.0 to communicate with clients. Requests to the API are JSON objects that contain one or more method invocations. Responses are also JSON objects that contain a result for each invocation in the request. See [JSON-RPC]. + +Both formats utilise JSON for the overall structure which are relatively simple and do not require any special client code, although there are client [SDKs] available. Some values contained within are XDR encoded and can be decoded using Stellar [SDKs]. + +## Endpoint Mapping + +Applications that use the following Horizon endpoints can typically migrate directly to the RPC using the referenced methods. + +Endpoints without mappings do not have a direct replacement in the RPC API. To build similar functionality in an application, take a look at other [Data] products. | Horizon Endpoint | RPC Method | |------------------|------------| @@ -13,8 +26,8 @@ When migrating from [Horizon] to [RPC], applications using [Horizon's REST API] | [`GET /ledgers/{seq}`] | [`getLedgers`] | | [`GET /ledgers/{seq}/transactions`] | [`getTransactions`] | | [`GET /ledgers/{seq}/operations`] | [`getTransactions`] | -| [`GET /ledgers/{seq}/payments`] | [`getEvents`]\* | -| [`GET /ledgers/{seq}/effects`] | [`getEvents`]\* | +| [`GET /ledgers/{seq}/payments`] | [`getEvents`] ⚠️ | +| [`GET /ledgers/{seq}/effects`] | [`getEvents`] ⚠️ | | [`POST /transactions`] | [`sendTransaction`] | | [`POST /transactions_async`] | [`sendTransaction`] | | [`GET /transactions`] | [`getTransactions`] | @@ -41,19 +54,21 @@ When migrating from [Horizon] to [RPC], applications using [Horizon's REST API] | [`GET /offers`] | - | | [`GET /offers/{id}`] | [`getLedgerEntries`] | | [`GET /offers/{id}/trades`] | - | -| [`GET /payments`] | [`getEvents`]\* | -| [`GET /effects`] | [`getEvents`]\* | -| [`GET /trades`] | [`getEvents`]\* | - -\* The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. +| [`GET /payments`] | [`getEvents`] ⚠️ | +| [`GET /effects`] | [`getEvents`] ⚠️ | +| [`GET /trades`] | [`getEvents`] ⚠️ | -\- The RPC API does not have a direct replacement for endpoints marked with a dash. To build similar functionality in an application, take a look at other [Data] products. +:::warning +The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. +::: [CAP-67]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md [Horizon]: horizon [RPC]: rpc -[Horizon's REST API]: horizon/api-reference +[Horizon's REST-like API]: horizon/api-reference +[Horizon's Response Format]: horizon/api-reference/structure/response-format [RPC JSON-RPC API]: rpc/api-reference +[JSON-RPC]: rpc/api-reference/json-rpc [Data]: ../data [`GET /`]: horizon/api-reference From 3f25fedeea9d0a983407fd075ec23fecd719f24b Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 13:11:27 +1000 Subject: [PATCH 5/7] fix missing link' --- docs/data/migrate-from-horizon-to-rpc/README.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/data/migrate-from-horizon-to-rpc/README.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx index 90e6de34c..257e5e55e 100644 --- a/docs/data/migrate-from-horizon-to-rpc/README.mdx +++ b/docs/data/migrate-from-horizon-to-rpc/README.mdx @@ -70,6 +70,7 @@ The [`getEvents`] method is not a direct replacement for Horizon's endpoints. Th [RPC JSON-RPC API]: rpc/api-reference [JSON-RPC]: rpc/api-reference/json-rpc [Data]: ../data +[SDKs]: ../tools/sdks/library [`GET /`]: horizon/api-reference [`GET /ledgers`]: horizon/api-reference/list-all-ledgers From fa21fd833406382080a26bb8142735588e59511f Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Mon, 3 Feb 2025 13:13:05 +1000 Subject: [PATCH 6/7] lint --- docs/data/migrate-from-horizon-to-rpc/README.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/data/migrate-from-horizon-to-rpc/README.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx index 257e5e55e..3d34afd74 100644 --- a/docs/data/migrate-from-horizon-to-rpc/README.mdx +++ b/docs/data/migrate-from-horizon-to-rpc/README.mdx @@ -20,7 +20,7 @@ Applications that use the following Horizon endpoints can typically migrate dire Endpoints without mappings do not have a direct replacement in the RPC API. To build similar functionality in an application, take a look at other [Data] products. | Horizon Endpoint | RPC Method | -|------------------|------------| +| --- | --- | | [`GET /`] | [`getLatestLedger`] [`getVersionInfo`] [`getHealth`] [`getNetwork`] | | [`GET /ledgers`] | [`getLedgers`] | | [`GET /ledgers/{seq}`] | [`getLedgers`] | @@ -59,7 +59,9 @@ Endpoints without mappings do not have a direct replacement in the RPC API. To b | [`GET /trades`] | [`getEvents`] ⚠️ | :::warning + The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. + ::: [CAP-67]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md @@ -71,7 +73,6 @@ The [`getEvents`] method is not a direct replacement for Horizon's endpoints. Th [JSON-RPC]: rpc/api-reference/json-rpc [Data]: ../data [SDKs]: ../tools/sdks/library - [`GET /`]: horizon/api-reference [`GET /ledgers`]: horizon/api-reference/list-all-ledgers [`GET /ledgers/{seq}`]: horizon/api-reference/retrieve-a-ledger @@ -108,7 +109,6 @@ The [`getEvents`] method is not a direct replacement for Horizon's endpoints. Th [`GET /payments`]: horizon/api-reference/list-all-payments [`GET /effects`]: horizon/api-reference/list-all-effects [`GET /trades`]: horizon/api-reference/get-all-trades - [`getLatestLedger`]: rpc/api-reference/methods/getLatestLedger [`getVersionInfo`]: rpc/api-reference/methods/getVersionInfo [`getHealth`]: rpc/api-reference/methods/getHealth From 496c2825d0a516edfe2ca9f6c90d5e2b852b7b89 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:12:10 +1000 Subject: [PATCH 7/7] add getTransactions to event locations and discussions about the two --- .../migrate-from-horizon-to-rpc/README.mdx | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/data/migrate-from-horizon-to-rpc/README.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx index 3d34afd74..05b2f7120 100644 --- a/docs/data/migrate-from-horizon-to-rpc/README.mdx +++ b/docs/data/migrate-from-horizon-to-rpc/README.mdx @@ -26,8 +26,8 @@ Endpoints without mappings do not have a direct replacement in the RPC API. To b | [`GET /ledgers/{seq}`] | [`getLedgers`] | | [`GET /ledgers/{seq}/transactions`] | [`getTransactions`] | | [`GET /ledgers/{seq}/operations`] | [`getTransactions`] | -| [`GET /ledgers/{seq}/payments`] | [`getEvents`] ⚠️ | -| [`GET /ledgers/{seq}/effects`] | [`getEvents`] ⚠️ | +| [`GET /ledgers/{seq}/payments`] | [`getEvents`] [`getTransactions`] ⚠️ | +| [`GET /ledgers/{seq}/effects`] | [`getEvents`] [`getTransactions`] ⚠️ | | [`POST /transactions`] | [`sendTransaction`] | | [`POST /transactions_async`] | [`sendTransaction`] | | [`GET /transactions`] | [`getTransactions`] | @@ -54,13 +54,23 @@ Endpoints without mappings do not have a direct replacement in the RPC API. To b | [`GET /offers`] | - | | [`GET /offers/{id}`] | [`getLedgerEntries`] | | [`GET /offers/{id}/trades`] | - | -| [`GET /payments`] | [`getEvents`] ⚠️ | -| [`GET /effects`] | [`getEvents`] ⚠️ | -| [`GET /trades`] | [`getEvents`] ⚠️ | +| [`GET /payments`] | [`getEvents`] [`getTransactions`] ⚠️ | +| [`GET /effects`] | [`getEvents`] [`getTransactions`] ⚠️ | +| [`GET /trades`] | [`getEvents`] [`getTransactions`] ⚠️ | + +:::tip + +The [`getTransactions`] method can be used to retrieve events batched by transaction. The events are contained in the meta XDR of the transaction (field `resultMetaXdr`). + +::: :::warning -The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. +The [`getEvents`] method is not a direct replacement for Horizon's endpoints. + +The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations. + +In the interim the [`getTransactions`] method can be used to retrieve the meta XDR of transactions containing non-contract operations to determine what movements of value have occurred. The meta XDR also contains events from contracts. :::