From 656e801cb5fab9e5beb565c905ba1ad3ac62a157 Mon Sep 17 00:00:00 2001 From: docs-agent Date: Thu, 7 May 2026 21:07:30 +0000 Subject: [PATCH] [docs-agent] Stellar API Try It: populate working defaults for all 12 methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 12 methods on the Stellar API page (https://www.alchemy.com/docs/stellar/stellar-api-overview) had empty Try It defaults because the OpenRPC source carried no `examples` blocks. The 5 methods sourced from `_components/custom/methods.yaml` (getHealth, getTransaction, getTransactions, sendTransaction, simulateTransaction) were also missing `paramStructure: by-name`, which Stellar RPC requires — Try It would have sent positional params and the server would have rejected them as "json: cannot unmarshal array into Go value of type protocol.GetTransactionRequest". Changes: - `_components/custom/methods.yaml`: add `paramStructure: by-name` to the 4 multi-param Stellar methods, plus an `examples` block to all 5. Only the Stellar chain spec references these methods (verified via grep), so this doesn't affect any other chain. - `_components/stellar/methods.yaml`: add `examples` blocks to the 7 Stellar-specific methods (getEvents, getFeeStats, getLatestLedger, getLedgerEntries, getLedgers, getNetwork, getVersionInfo). Verified live against https://stellar-mainnet.g.alchemy.com/v2/docs-demo: all 12 examples now return non-error JSON-RPC responses. The simulateTransaction example (call name() on the native XLM SAC) returns a stable "native" result indefinitely; sendTransaction submits the same unsigned envelope and returns status: ERROR with errorResultXdr — a clean schema demo without spending real funds. Caveat: getEvents / getTransactions / getTransaction reference recent ledgers/hashes. Stellar RPC retains ~7 days of events and ~14 days of transactions, so those three example values will need periodic refresh. The other 9 methods (incl. getLedgers using ledger 60000000, getLedgerEntries using stable contract instance + USDC issuer keys) are stable indefinitely. Refs DOCS-74 Requested-by: @dexterliu --- .../chains/_components/custom/methods.yaml | 48 ++++++++++++++ .../chains/_components/stellar/methods.yaml | 62 +++++++++++++++++++ 2 files changed, 110 insertions(+) diff --git a/src/openrpc/chains/_components/custom/methods.yaml b/src/openrpc/chains/_components/custom/methods.yaml index e0664ea64..9c815da1a 100644 --- a/src/openrpc/chains/_components/custom/methods.yaml +++ b/src/openrpc/chains/_components/custom/methods.yaml @@ -1970,11 +1970,15 @@ components: latestLedger: 50000 oldestLedger: 1 ledgerRetentionWindow: 17280 + examples: + - name: getHealth example + params: [] sendTransaction: name: sendTransaction summary: Send transaction description: Submits a signed transaction to the network. + paramStructure: by-name params: - name: transaction required: true @@ -1986,11 +1990,22 @@ components: description: Transaction submission result. schema: type: object + examples: + - name: sendTransaction example + description: | + Submits a base64-encoded TransactionEnvelope XDR. The default value below is an unsigned envelope + that calls `name()` on the native XLM Stellar Asset Contract; resubmitting it returns + `status: "ERROR"` with an `errorResultXdr` so you can see the response shape without sending real funds. + Replace the value with your own signed envelope to actually submit a transaction. + params: + - name: transaction + value: "AAAAAgAAAAA7mRE4Dv6Yi6CokA6xz+RPNm99vpRr7QdyQPf2JN8VxQAAAGQAAAAAAAAAZQAAAAEAAAAAAAAAAAAAAABp/P05AAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABJbT82FmuwvpjSEOMSJs8PBDJi20hvk/TyzDLaJU++XcAAAAEbmFtZQAAAAAAAAAAAAAAAAAAAAA=" getTransaction: name: getTransaction summary: Get transaction description: Returns the details and status of a submitted transaction by its hash. + paramStructure: by-name params: - name: hash required: true @@ -2013,11 +2028,20 @@ components: latestLedgerCloseTime: { type: integer } oldestLedger: { type: integer } oldestLedgerCloseTime: { type: integer } + examples: + - name: getTransaction example + description: | + Looks up a real successful Stellar mainnet transaction. Stellar RPC retains transactions + for ~14 days, so this hash will eventually age out and need to be replaced with a fresher one. + params: + - name: hash + value: "86d85a0db4d7cdf2aa8e4b633e050e8c3c138deae7cac62ff4d4ff5fb732fe96" getTransactions: name: getTransactions summary: Get transactions description: Returns a paginated list of transactions from the network. + paramStructure: by-name params: - name: startLedger required: false @@ -2046,11 +2070,24 @@ components: transactions: { type: array, items: { type: object } } latestLedger: { type: integer } cursor: { type: string } + examples: + - name: getTransactions example + description: | + Returns one transaction starting at a recent mainnet ledger. Stellar RPC keeps roughly + the last 14 days of transactions; if the example ledger has aged out, replace `startLedger` + with a value within the current retention window (see `oldestLedger` from `getHealth`). + params: + - name: startLedger + value: 62462511 + - name: pagination + value: + limit: 1 simulateTransaction: name: simulateTransaction summary: Simulate transaction description: Simulates a transaction invocation to estimate resource fees, required authorizations, and return values without submitting to the network. + paramStructure: by-name params: - name: transaction required: true @@ -2083,3 +2120,14 @@ components: latestLedger: { type: integer } minResourceFee: { type: string } transactionData: { type: string } + examples: + - name: simulateTransaction example + description: | + Simulates a read-only call to `name()` on the native XLM Stellar Asset Contract + (`CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA`). The envelope is unsigned — + simulation never checks signatures, sequence numbers, or time bounds, so this example + is stable indefinitely and returns the SCV-encoded string `"native"` in `results[0].xdr` + along with a populated `minResourceFee`, `transactionData`, and `events`. + params: + - name: transaction + value: "AAAAAgAAAAA7mRE4Dv6Yi6CokA6xz+RPNm99vpRr7QdyQPf2JN8VxQAAAGQAAAAAAAAAZQAAAAEAAAAAAAAAAAAAAABp/P05AAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABJbT82FmuwvpjSEOMSJs8PBDJi20hvk/TyzDLaJU++XcAAAAEbmFtZQAAAAAAAAAAAAAAAAAAAAA=" diff --git a/src/openrpc/chains/_components/stellar/methods.yaml b/src/openrpc/chains/_components/stellar/methods.yaml index c30017037..6f56b419e 100644 --- a/src/openrpc/chains/_components/stellar/methods.yaml +++ b/src/openrpc/chains/_components/stellar/methods.yaml @@ -108,6 +108,29 @@ components: title: xdrFormat type: string description: Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json'). + examples: + - name: Native XLM transfer events + description: | + Returns up to 2 native XLM `transfer` contract events emitted from the Stellar Asset Contract + (`CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA`) starting near the current head. + Stellar RPC retains roughly the last 7 days of events, so `startLedger` may need to be bumped + forward over time. The first topic `AAAADwAAAAh0cmFuc2Zlcg==` is the SCV-encoded `transfer` symbol. + params: + - name: startLedger + value: 62463000 + - name: filters + value: + - type: contract + contractIds: + - CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA + topics: + - - AAAADwAAAAh0cmFuc2Zlcg== + - "*" + - "*" + - "**" + - name: pagination + value: + limit: 2 result: name: getEventsResult schema: @@ -192,6 +215,9 @@ components: url: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getFeeStats paramStructure: by-name params: [] + examples: + - name: getFeeStats example + params: [] result: name: getFeeStatsResult schema: @@ -313,6 +339,9 @@ components: url: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getLatestLedger paramStructure: by-name params: [] + examples: + - name: getLatestLedger example + params: [] result: name: getLatestLedgerResponse schema: @@ -372,6 +401,20 @@ components: title: xdrFormat type: string description: Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json'). + examples: + - name: Account and contract instance entries + description: | + Looks up two stable mainnet ledger entries: the **Account** entry for the Circle USDC issuer + (`GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`) and the + **ContractInstance** entry for the native XLM Stellar Asset Contract + (`CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA`). Both are permanent ledger + entries, so this example is stable indefinitely. To build your own `LedgerKey`s see + [Building ledger keys](https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getLedgerEntries#building-ledger-keys). + params: + - name: keys + value: + - "AAAAAAAAAAA7mRE4Dv6Yi6CokA6xz+RPNm99vpRr7QdyQPf2JN8VxQ==" + - "AAAABgAAAAEltPzYWa7C+mNIQ4xImzw8EMmLbSG+T9PLMMtolT75dwAAABQAAAAB" result: name: getLedgerEntriesResult schema: @@ -442,6 +485,19 @@ components: title: xdrFormat type: string description: Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json'). + examples: + - name: Two ledgers from a stable historical sequence + description: | + Returns two consecutive ledger summaries starting at sequence 60,000,000. + Unlike `getEvents` and `getTransactions` (which retain ~7 and ~14 days respectively), + Alchemy's Stellar mainnet RPC retains full ledger history back to genesis (ledger 2), + so this example is stable indefinitely. + params: + - name: startLedger + value: 60000000 + - name: pagination + value: + limit: 2 result: name: getLedgersResult schema: @@ -497,6 +553,9 @@ components: url: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getNetwork paramStructure: by-name params: [] + examples: + - name: getNetwork example + params: [] result: name: getNetworkResult schema: @@ -643,6 +702,9 @@ components: url: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getVersionInfo paramStructure: by-name params: [] + examples: + - name: getVersionInfo example + params: [] result: name: getVersionInfoResult schema: