diff --git a/docs/anchoring-assets/anchor-platform/component/observer/observer.mdx b/docs/anchoring-assets/anchor-platform/component/observer/observer.mdx new file mode 100644 index 000000000..74d1788fc --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/observer/observer.mdx @@ -0,0 +1,36 @@ +Using the Payment Observer allows you to delegate this step to the Anchor Platform. To enable the Payment Observer, use the `--stellar-observer` flag in the command section of the [compose file](#configuration). + +The Payment Observer will track all transactions sent to the distribution account. When the transaction with the expected memo is detected in the network, the status will automatically change to `pending_anchor` and event will be the emitted (if Kafka is used). + +In order to update the transaction's statuses, the observer makes corresponding JSON-RPC requests to the platform. It should use the following URL. + + + +```bash +# dev.env +PLATFORM_API_BASE_URL=http://platform-server:8085 +``` + + + +:::caution + +The Payment Observer won't validate the amounts. It's your responsibility to verify that the amount sent by the user is correct. + +::: + +:::info + +If you already have a system that monitors payments, make sure that the logic of the system matches the description below: + +First, wait for the transaction to be included in the ledger (using an SDK). This transaction must have the expected memo and destination address (distribution account). Once this transaction has been detected and verified, notify the user that the funds have been received using the [notify_onchain_funds_received](#onchain-funds-received) JSON-RPC request. + +::: + +:::tip + +The Fireblocks custody service will automatically track transactions and notify the user that the funds have been received. See the [Fireblocks custody service documentation][fireblocks] for more details. + +::: + +[fireblocks]: /docs/category/fireblocks diff --git a/docs/anchoring-assets/anchor-platform/component/rpc/error.mdx b/docs/anchoring-assets/anchor-platform/component/rpc/error.mdx new file mode 100644 index 000000000..27746e6f0 --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/rpc/error.mdx @@ -0,0 +1,16 @@ +
+ +| Error code | Meaning | +| :--------- | :------------------------------------------- | +| -32600 | The JSON sent is not a valid Request object | +| -32601 | The method does not exist / is not available | +| -32602 | Invalid method parameter(s) | +| -32603 | Internal JSON-RPC error | + +
+ +:::tip + +We will also reference a `$transaction_id` variable. This is an identification of transaction that is being returned from the Anchor Platform on an withdrawal or deposit start request. You can obtain the transaction ID by connecting the test wallet to your local Anchor Platform instance. + +::: diff --git a/docs/anchoring-assets/anchor-platform/component/rpc/request.mdx b/docs/anchoring-assets/anchor-platform/component/rpc/request.mdx new file mode 100644 index 000000000..9157143af --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/rpc/request.mdx @@ -0,0 +1,29 @@ +The Request object must contain the following attributes: + + + +- ATTRIBUTE + - DATA TYPE + - DESCRIPTION +- jsonrpc + - string + - A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0" +- method + - string + - A String containing the name of the method to be invoked. List of available methods you can see in [JSON-RPC Methods][json-rpc-methods] +- params + - object + - A Structured value that holds the parameter values, corresponding to method call, to be used during the invocation of the method +- id + - string + - An identifier established by the client. The Server will reply with the same value in the Response object + + + +:::tip + +It's possible to provide multiple updates in a single JSON-RPC request (by placing multiple JSON-RPC request objects). When an update is done in this way, all updates will be done sequentially. + +Most importantly, each JSON-RPC request is not atomic. If one update fails, all previous updates WILL be applied and all subsequent updates WILL be processed and applied as well. + +::: diff --git a/docs/anchoring-assets/anchor-platform/component/rpc/response.mdx b/docs/anchoring-assets/anchor-platform/component/rpc/response.mdx new file mode 100644 index 000000000..02d808103 --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/rpc/response.mdx @@ -0,0 +1,33 @@ +The Response is expressed as a single JSON Object, with the following attributes: + + + +- ATTRIBUTE + - DATA TYPE + - DESCRIPTION +- jsonrpc + - string + - A String specifying the version of the JSON-RPC protocol. It's set to "2.0" +- result + - object + - A Structured value that holds the updated transaction details +- id + - string + - An identifier sent by the client +- error + - object + - A Structured value that holds the error details + - id + - string + - Unique id of the transaction for which an error occurred + - code + - number + - A number that indicates the error type that occurred. Please see a list of [error codes](#error-codes) below + - message + - string + - A String providing a short description of the error + - data + - string + - A primitive or structured value that contains additional information about the error + + diff --git a/docs/anchoring-assets/anchor-platform/component/rpc/rpc.mdx b/docs/anchoring-assets/anchor-platform/component/rpc/rpc.mdx new file mode 100644 index 000000000..f00b8ee7f --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/rpc/rpc.mdx @@ -0,0 +1,17 @@ +Before making JSON-RPC requests, let's first create a template for making a request to the Anchor Platform. + + + +```bash +# call-json-rpc.sh +#!/usr/bin/env bash + +curl localhost:8085 \ + -X POST \ + -H 'Content-Type: application/json' \ + --data "@$1" +``` + + + +This small script will make a JSON-RPC request to the Anchor Platform hosted on the default port (8085). JSON transaction data stored in the provided file will be used as body (requests must be an array). diff --git a/docs/anchoring-assets/anchor-platform/component/security/api_key.mdx b/docs/anchoring-assets/anchor-platform/component/security/api_key.mdx new file mode 100644 index 000000000..f16c47f7a --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/security/api_key.mdx @@ -0,0 +1,14 @@ +To enable API key authentication, modify your `dev.env` file: + + + +```bash +# dev.env +PLATFORM_SERVER_AUTH_TYPE=api_key +# Will be used as API key +SECRET_PLATFORM_API_AUTH_SECRET="your API key that business server will use" +``` + + + +After it's enabled, all requests must contain a valid `X-Api-Key` header, set to the configured API key. diff --git a/docs/anchoring-assets/anchor-platform/component/security/jwt.mdx b/docs/anchoring-assets/anchor-platform/component/security/jwt.mdx new file mode 100644 index 000000000..f16c47f7a --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/security/jwt.mdx @@ -0,0 +1,14 @@ +To enable API key authentication, modify your `dev.env` file: + + + +```bash +# dev.env +PLATFORM_SERVER_AUTH_TYPE=api_key +# Will be used as API key +SECRET_PLATFORM_API_AUTH_SECRET="your API key that business server will use" +``` + + + +After it's enabled, all requests must contain a valid `X-Api-Key` header, set to the configured API key. diff --git a/docs/anchoring-assets/anchor-platform/component/security/security.mdx b/docs/anchoring-assets/anchor-platform/component/security/security.mdx new file mode 100644 index 000000000..76a3832c3 --- /dev/null +++ b/docs/anchoring-assets/anchor-platform/component/security/security.mdx @@ -0,0 +1,11 @@ +:::caution + +By default, the Platform API's endpoints such as `GET /transactions` and `GET /transactions/:id` are not protected, and are accessible by anyone who has access to the server, including wallet applications. + +::: + +:::info + +It's recommended to keep Platform server accessible only from the private network. However, you may want to add additional layer of protection via securing the API. + +::: diff --git a/docs/anchoring-assets/anchor-platform/sep24/integration.mdx b/docs/anchoring-assets/anchor-platform/sep24/integration.mdx index 1c8abc49f..a271f2145 100644 --- a/docs/anchoring-assets/anchor-platform/sep24/integration.mdx +++ b/docs/anchoring-assets/anchor-platform/sep24/integration.mdx @@ -5,6 +5,14 @@ sidebar_position: 30 import { CodeExample } from "@site/src/components/CodeExample"; import { AttributeTable } from "@site/src/components/AttributeTable"; +import Security from "../component/security/security.mdx"; +import UsingApiKey from "../component/security/api_key.mdx"; +import UsingJwt from "../component/security/jwt.mdx"; +import Rpc from "../component/rpc/rpc.mdx"; +import RpcRequest from "../component/rpc/request.mdx"; +import RpcResponse from "../component/rpc/response.mdx"; +import RpcError from "../component/rpc/error.mdx"; +import Observer from "../component/observer/observer.mdx"; One of the main points of interaction with the Anchor Platform is notifying the Anchor Platform about events related to the transaction. @@ -25,157 +33,31 @@ You can find out more about transaction flow and statuses in the [SEP-24 protoco ## Securing Platform API -:::caution - -By default, the Platform API's endpoints such as `GET /transactions` and `GET /transactions/:id` are not protected, and are accessible by anyone who has access to the server, including wallet applications. - -::: - -:::info - -It's recommended to keep Platform server accessible only from the private network. However, you may want to add additional layer of protection via securing the API. - -::: + ### Using API Key -To enable API key authentication, modify your `dev.env` file: - - - -```bash -# dev.env -PLATFORM_SERVER_AUTH_TYPE=api_key -# Will be used as API key -SECRET_PLATFORM_API_AUTH_SECRET="your API key that business server will use" -``` - - - -After it's enabled, all requests must contain a valid `X-Api-Key` header, set to the configured API key. + ### Using JWT -To enable JWT authentication, modify your `dev.env` file: - - - -```bash -# dev.env -PLATFORM_SERVER_AUTH_TYPE=jwt -SECRET_PLATFORM_API_AUTH_SECRET="your encryption key shared with your business server" -``` - - - -After it's enabled, all requests must contain a valid `Authorization` header. The JWT provided must have the `jti` and `exp` fields representing a valid transaction and token expiration time, respectively. + ## Making JSON-RPC Requests -Before making JSON-RPC requests, let's first create a template for making a request to the Anchor Platform. - - - -```bash -# call-json-rpc.sh -#!/usr/bin/env bash - -curl localhost:8085 \ - -X POST \ - -H 'Content-Type: application/json' \ - --data "@$1" -``` - - - -This small script will make a JSON-RPC request to the Anchor Platform hosted on the default port (8085). JSON transaction data stored in the provided file will be used as body (requests must be an array). + ### JSON-RPC Request -The Request object must contain the following attributes: - - - -- ATTRIBUTE - - DATA TYPE - - DESCRIPTION -- jsonrpc - - string - - A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0" -- method - - string - - A String containing the name of the method to be invoked. List of available methods you can see in [JSON-RPC Methods][json-rpc-methods] -- params - - object - - A Structured value that holds the parameter values, corresponding to method call, to be used during the invocation of the method -- id - - string - - An identifier established by the client. The Server will reply with the same value in the Response object - - - -:::tip - -It's possible to provide multiple updates in a single JSON-RPC request (by placing multiple JSON-RPC request objects). When an update is done in this way, all updates will be done sequentially. - -Most importantly, each JSON-RPC request is not atomic. If one update fails, all previous updates WILL be applied and all subsequent updates WILL be processed and applied as well. - -::: + ### JSON-RPC Response -The Response is expressed as a single JSON Object, with the following attributes: - - - -- ATTRIBUTE - - DATA TYPE - - DESCRIPTION -- jsonrpc - - string - - A String specifying the version of the JSON-RPC protocol. It's set to "2.0" -- result - - object - - A Structured value that holds the updated transaction details -- id - - string - - An identifier sent by the client -- error - - object - - A Structured value that holds the error details - - id - - string - - Unique id of the transaction for which an error occurred - - code - - number - - A number that indicates the error type that occurred. Please see a list of [error codes](#error-codes) below - - message - - string - - A String providing a short description of the error - - data - - string - - A primitive or structured value that contains additional information about the error - - + ### Error Codes -
- -| Error code | Meaning | -| :--------- | :------------------------------------------- | -| -32600 | The JSON sent is not a valid Request object | -| -32601 | The method does not exist / is not available | -| -32602 | Invalid method parameter(s) | -| -32603 | Internal JSON-RPC error | - -
- -:::tip - -We will also reference a `$transaction_id` variable. This is an identification of transaction that is being returned from the Anchor Platform on an interactive withdrawal or deposit start request. You can obtain the transaction ID by connecting the test wallet to your local Anchor Platform instance. - -::: + ## Updating Deposit Transaction Via JSON-RPC @@ -1083,51 +965,8 @@ Works in the same manner as for the deposit flow. For more details, see [Transac ## Tracking Stellar Transactions -Using the Payment Observer allows you to delegate this step to the Anchor Platform. To enable the Payment Observer, use the `--stellar-observer` flag in the command section of the [compose file](#configuration). - -The Payment Observer will track all transactions sent to the distribution account. When the transaction with the expected memo is detected in the network, the status will automatically change to `pending_anchor` and event will be the emitted (if Kafka is used). - -In order to update the transaction's statuses, the observer makes corresponding JSON-RPC requests to the platform. It should use the following URL. - - - -```bash -# dev.env -PLATFORM_API_BASE_URL=http://platform-server:8085 -``` - - - -:::caution - -The Payment Observer won't validate the amounts. It's your responsibility to verify that the amount sent by the user is correct. - -::: - -:::info - -If you already have a system that monitors payments, make sure that the logic of the system matches the description below: - -First, wait for the transaction to be included in the ledger (using an SDK). This transaction must have the expected memo and destination address (distribution account). Once this transaction has been detected and verified, notify the user that the funds have been received using the [notify_onchain_funds_received](#onchain-funds-received) JSON-RPC request. + -[sep-1]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md [sep-9]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0009.md [sep-24]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md -[sep-38]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md -[sep24-get-info]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#info -[anchor-platform-image]: https://hub.docker.com/r/stellar/anchor-platform -[docker-compose]: https://docs.docker.com/compose/ -[minikube]: https://minikube.sigs.k8s.io/docs/ -[kubernetes]: https://kubernetes.io/ -[nginx]: https://www.nginx.com/ -[ap-default-values]: https://github.com/stellar/java-stellar-anchor-sdk/blob/develop/platform/src/main/resources/config/anchor-config-default-values.yaml -[stellar-demo-wallet]: https://demo-wallet.stellar.org -[stellar-lab]: https://laboratory.stellar.org/ -[postgresql]: https://www.postgresql.org/ -[aurora-postgresql]: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraPostgreSQL.html -[h2]: https://www.h2database.com/html/main.html -[sqlite]: https://www.sqlite.org/index.html -[flyway]: https://documentation.red-gate.com/fd/welcome-to-flyway-184127914.html -[sep-24-ref-ui]: https://github.com/stellar/sep24-reference-ui -[sep-24-ref]: https://github.com/stellar/java-stellar-anchor-sdk/tree/develop/kotlin-reference-server [json-rpc-methods]: /api/anchor-platform/rpc/methods diff --git a/docs/anchoring-assets/anchor-platform/sep6/integration.mdx b/docs/anchoring-assets/anchor-platform/sep6/integration.mdx index 0f8830429..5ee5e5331 100644 --- a/docs/anchoring-assets/anchor-platform/sep6/integration.mdx +++ b/docs/anchoring-assets/anchor-platform/sep6/integration.mdx @@ -5,6 +5,14 @@ sidebar_position: 30 import { CodeExample } from "@site/src/components/CodeExample"; import { AttributeTable } from "@site/src/components/AttributeTable"; +import Security from "../component/security/security.mdx"; +import UsingApiKey from "../component/security/api_key.mdx"; +import UsingJwt from "../component/security/jwt.mdx"; +import Rpc from "../component/rpc/rpc.mdx"; +import RpcRequest from "../component/rpc/request.mdx"; +import RpcResponse from "../component/rpc/response.mdx"; +import RpcError from "../component/rpc/error.mdx"; +import Observer from "../component/observer/observer.mdx"; One of the main points of interaction with the Anchor Platform is notifying the Platform about events related to transactions. @@ -28,157 +36,31 @@ You can find out more about transaction flow and statuses in the [SEP-6 protocol ## Securing Platform API -:::caution - -By default, the Platform API's endpoints such as `GET /transactions` and `GET /transactions/:id` are not protected, and are accessible by anyone who has access to the server, including wallet applications. - -::: - -:::info - -It's recommended to keep Platform server accessible only from the private network. However, you may want to add additional layer of protection via securing the API. - -::: + ### Using API Key -To enable API key authentication, modify your `dev.env` file: - - - -```bash -# dev.env -PLATFORM_SERVER_AUTH_TYPE=api_key -# Will be used as API key -SECRET_PLATFORM_API_AUTH_SECRET="your API key that business server will use" -``` - - - -After it's enabled, all requests must contain a valid `X-Api-Key` header, set to the configured API key. + ### Using JWT -To enable JWT authentication, modify your `dev.env` file: - - - -```bash -# dev.env -PLATFORM_SERVER_AUTH_TYPE=jwt -SECRET_PLATFORM_API_AUTH_SECRET="your encryption key shared with your business server" -``` - - - -After it's enabled, all requests must contain a valid `Authorization` header. The JWT provided must have the `jti` and `exp` fields representing a valid transaction and token expiration time, respectively. + ## Making JSON-RPC Requests -Before making JSON-RPC requests, let's first create a template for making a request to the Anchor Platform. - - - -```bash -# call-json-rpc.sh -#!/usr/bin/env bash - -curl localhost:8085 \ - -X POST \ - -H 'Content-Type: application/json' \ - --data "@$1" -``` - - - -This small script will make a JSON-RPC request to the Anchor Platform hosted on the default port (8085). JSON transaction data stored in the provided file will be used as body (requests must be an array). + ### JSON-RPC Request -The Request object must contain the following attributes: - - - -- ATTRIBUTE - - DATA TYPE - - DESCRIPTION -- jsonrpc - - string - - A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0" -- method - - string - - A String containing the name of the method to be invoked. List of available methods you can see in [JSON-RPC Methods][json-rpc-methods] -- params - - object - - A Structured value that holds the parameter values, corresponding to method call, to be used during the invocation of the method -- id - - string - - An identifier established by the client. The Server will reply with the same value in the Response object - - - -:::tip - -It's possible to provide multiple updates in a single JSON-RPC request (by placing multiple JSON-RPC request objects). When an update is done in this way, all updates will be done sequentially. - -Most importantly, each JSON-RPC request is not atomic. If one update fails, all previous updates WILL be applied and all subsequent updates WILL be processed and applied as well. - -::: + ### JSON-RPC Response -The Response is expressed as a single JSON Object, with the following attributes: - - - -- ATTRIBUTE - - DATA TYPE - - DESCRIPTION -- jsonrpc - - string - - A String specifying the version of the JSON-RPC protocol. It's set to "2.0" -- result - - object - - A Structured value that holds the updated transaction details -- id - - string - - An identifier sent by the client -- error - - object - - A Structured value that holds the error details - - id - - string - - Unique id of the transaction for which an error occurred - - code - - number - - A number that indicates the error type that occurred. Please see a list of [error codes](#error-codes) below - - message - - string - - A String providing a short description of the error - - data - - string - - A primitive or structured value that contains additional information about the error - - + ### Error Codes -
- -| Error code | Meaning | -| :--------- | :------------------------------------------- | -| -32600 | The JSON sent is not a valid Request object | -| -32601 | The method does not exist / is not available | -| -32602 | Invalid method parameter(s) | -| -32603 | Internal JSON-RPC error | - -
- -:::tip - -We will also reference a `$transaction_id` variable. This is an identification of transaction that is being returned from the Anchor Platform on an withdrawal or deposit start request. You can obtain the transaction ID by connecting the test wallet to your local Anchor Platform instance. - -::: + ## Updating Deposit (Exchange) Transaction Via JSON-RPC @@ -1095,40 +977,6 @@ Works in the same manner as for the deposit flow. For more details, see [Transac ## Tracking Stellar Transactions -Using the Payment Observer allows you to delegate this step to the Anchor Platform. To enable the Payment Observer, use the `--stellar-observer` flag in the command section of the [compose file](#configuration). - -The Payment Observer will track all transactions sent to the distribution account. When the transaction with the expected memo is detected in the network, the status will automatically change to `pending_anchor` and event will be the emitted (if Kafka is used). - -In order to update the transaction's statuses, the observer makes corresponding JSON-RPC requests to the platform. It should use the following URL. - - - -```bash -# dev.env -PLATFORM_API_BASE_URL=http://platform-server:8085 -``` - - - -:::caution - -The Payment Observer won't validate the amounts. It's your responsibility to verify that the amount sent by the user is correct. - -::: - -:::info - -If you already have a system that monitors payments, make sure that the logic of the system matches the description below: - -First, wait for the transaction to be included in the ledger (using an SDK). This transaction must have the expected memo and destination address (distribution account). Once this transaction has been detected and verified, notify the user that the funds have been received using the [notify_onchain_funds_received](#onchain-funds-received) JSON-RPC request. - -::: - -:::tip - -The Fireblocks custody service will automatically track transactions and notify the user that the funds have been received. See the [Fireblocks custody service documentation][fireblocks] for more details. - -::: + [get-transactions]: /api/anchor-platform/resources/get-transactions -[fireblocks]: /docs/category/fireblocks