Skip to content

[docs-agent] Stellar API Try It: populate working defaults for all 12 methods #1288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JackReacher0807 wants to merge 1 commit into
base: main
Choose a base branch
from
+110 −0
Open

[docs-agent] Stellar API Try It: populate working defaults for all 12 methods #1288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions src/openrpc/chains/_components/custom/methods.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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"
Comment on lines +2037 to +2038
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid hard-coded retention-window defaults

These Try It defaults are static but point at data that Stellar RPC only serves within a recent retention window: the example itself notes the hash will age out, and the same pattern is used for getTransactions and getEvents start ledgers. Once that window passes, new users running the default examples will get NOT_FOUND/old-ledger errors instead of the advertised populated response shape (Stellar documents recent retention for these methods: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getTransaction). Consider using defaults that do not depend on expiring history, or generating/refreshing these values automatically.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

@JackReacher0807 JackReacher0807 May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acknowledged but not changing. The staleness is a deliberate trade-off, called out in the PR description under Caveat on staleness: 9 of the 12 methods (getFeeStats, getHealth, getLatestLedger, getLedgerEntries, getLedgers, getNetwork, getVersionInfo, sendTransaction, simulateTransaction) are stable indefinitely. Only getEvents, getTransactions, and getTransaction reference values inside Stellar RPC's retention window (~7d for events, ~14d for transactions).

The alternative the bot is suggesting (synthetic defaults that don't depend on expiring history) is exactly what the PR replaces: empty/synthetic placeholders that returned no data when users clicked Try It. Real values that occasionally need refresh are a strict improvement over permanently broken examples.

Auto-refresh is the right long-term answer but it's a docs pipeline change (probably a scheduled GitHub Action that hits the live RPC, picks the latest finalized ledger / a recent successful tx hash, and rewrites the example block). Out of scope for this PR. Tracking the periodic-refresh maintenance burden in the Linear thread.


getTransactions:
name: getTransactions
summary: Get transactions
description: Returns a paginated list of transactions from the network.
paramStructure: by-name
params:
- name: startLedger
required: false
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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="
62 changes: 62 additions & 0 deletions src/openrpc/chains/_components/stellar/methods.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
Loading