diff --git a/docs/modules/ROOT/pages/stellar.adoc b/docs/modules/ROOT/pages/stellar.adoc index b60385136..a148f7e21 100644 --- a/docs/modules/ROOT/pages/stellar.adoc +++ b/docs/modules/ROOT/pages/stellar.adoc @@ -150,9 +150,10 @@ The relayer supports three ways to submit transactions: 1. **Operations-based**: Build a transaction by specifying the `operations` array (recommended for most use cases) 2. **Transaction XDR (unsigned)**: Submit a pre-built unsigned transaction using `transaction_xdr` field (advanced use case) -3. **Transaction XDR (signed) with fee bump**: Submit a signed transaction using `transaction_xdr` with `fee_bump: true` to wrap it in a fee bump transaction +3. **Transaction XDR (signed)**: Submit a signed transaction using `transaction_xdr` with `fee_bump: true` (required for signed XDR) to wrap it in a fee bump transaction + +==== Example 1: Operations-based Transaction -Example: Send Transaction [source,bash] ---- curl --location --request POST 'http://localhost:8080/api/v1/relayers//transactions' \ @@ -172,6 +173,56 @@ curl --location --request POST 'http://localhost:8080/api/v1/relayers//transactions' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "network": "testnet", + "transaction_xdr": "AAAAAgAAAACige4lTdwSB/sto4SniEdJ2kOa2X65s5bqkd40J4DjSwAAAGQAAHAkAAAADgAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAKKB7iVN3BIH+y2jhKeIR0naQ5rZfrmzluqR3jQngONLAAAAAAAAAAAAD0JAAAAAAAAAAAA=" +}' +---- + +The `transaction_xdr` field should contain a base64-encoded unsigned transaction envelope. This is useful when: +- You need precise control over transaction structure +- You want to use advanced Stellar features not exposed via the operations API + +==== Example 3: Signed Transaction XDR + +Submit a pre-signed transaction with fee bump wrapper. **Note: `fee_bump: true` is required when submitting signed XDR**: + +[source,bash] +---- +curl --location --request POST 'http://localhost:8080/api/v1/relayers//transactions' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "network": "testnet", + "transaction_xdr": "AAAAAgAAAABjc+mbXCnvmVk4lxqVl7s0LAz5slXqmkHBg8PpH7p3DgAAAGQABpK0AAAACQAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAGN0qQBW8x3mfbwGGYndt2uq4O4sZPUrDx5HlwuQke9zAAAAAAAAAAAAAA9CAAAAAQAAAAA=", + "fee_bump": true, + "max_fee": 10000000 +}' +---- + +The fee bump feature is useful when: +- You have a pre-signed transaction from another system or wallet +- You want the relayer to pay transaction fees on behalf of the original signer +- You need to increase the fee for a transaction to ensure timely execution + +[IMPORTANT] +==== +When using `transaction_xdr`: +- The XDR must be properly formatted and valid for the target network +- For unsigned XDR, the relayer will add its signature before submission +- **For signed XDR, `fee_bump: true` is mandatory** - the relayer requires this to wrap the signed transaction in a fee bump envelope +- The `max_fee` parameter (in stroops) controls the maximum fee for fee bump transactions (defaults to 1,000,000 = 0.1 XLM) +==== + See link:https://release-v1-0-0%2D%2Dopenzeppelin-relayer.netlify.app/api_docs.html[API Reference^] for full details and examples. === Asset Types