[chore] SDK examples: Java v3.1.0 audit - #2544
Merged
Merged
Conversation
Standing-correctness audit against java-stellar-sdk 3.1.0. The 1.0.0
package/builder reorg left several examples using classes and builders
that no longer exist at the referenced locations (verified against the
3.1.0 source tree). Import package root is unchanged (`org.stellar.sdk`);
only the moved classes and the removed nested builders were updated.
- invoke-contract-tx-sdk.mdx & stellar-transaction.mdx: exceptions moved
to `org.stellar.sdk.exception.*`, `InvokeHostFunctionOperation` to
`org.stellar.sdk.operations.*`; `SorobanRpcErrorResponse` was renamed
to `SorobanRpcException` (in `org.stellar.sdk.exception`). Updated the
imports and the `throws` clauses.
- control-asset-access.mdx: `Transaction.Builder` -> `TransactionBuilder`
(which requires `setBaseFee`/`setTimeout`); nested
`SetOptionsOperation.Builder().setSetFlags(...)` -> Lombok
`SetOptionsOperation.builder().setFlags(...)`; imported the operation
from `org.stellar.sdk.operations`.
- create-account.mdx: nested `CreateAccountOperation.Builder(id, "5")`
-> `CreateAccountOperation.builder().destination(id)
.startingBalance(new BigDecimal("5"))`; `Asset.createNonNative` ->
`Asset.createNonNativeAsset`; added the operations and BigDecimal
imports.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
….1.0 Follow-up to the java-stellar-sdk 3.1.0 audit: this file's five Java snippets still used the pre-1.0.0 API (verified against the 3.1.0 source tree). - `new Transaction.Builder(acct, net)` -> `new TransactionBuilder(...)`, which requires an explicit base fee/timeout, so added `.setBaseFee(Transaction.MIN_BASE_FEE)` (and `.setTimeout` where the runnable snippets lacked it). - Nested operation builders replaced with Lombok `builder()`: `ChangeTrustOperation` (asset is now `ChangeTrustAsset`, limit is `BigDecimal`), `PaymentOperation` (amount is `BigDecimal`), `SetOptionsOperation` (`setMasterKeyWeight` -> `masterKeyWeight`). - Per-operation source: `.setSourceAccount(id)` -> `.sourceAccount(id)`. - `SetTrustLineFlagsOperation` was renamed `SetTrustlineFlagsOperation`; the removed `.setAuthorized(true)` convenience is now `.setFlags(EnumSet.of(TrustLineFlags.AUTHORIZED_FLAG))`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Stellar documentation Java snippets to align with java-stellar-sdk v3.1.0 APIs (notably the newer TransactionBuilder / *.builder() patterns) so readers can copy/paste examples against the current SDK.
Changes:
- Migrated classic transaction examples from
new Transaction.Builder(...)/new *Operation.Builder(...)tonew TransactionBuilder(...)and*Operation.builder(). - Updated Soroban examples to use the newer exception packages (
org.stellar.sdk.exception.*) and operation package (org.stellar.sdk.operations.*). - Adjusted some examples to use
BigDecimal-based amount/balance setters.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tokens/how-to-issue-an-asset.mdx | Updates asset issuance examples to v3.1.0 builder APIs (trustlines, payments, flags, set options). |
| docs/tokens/control-asset-access.mdx | Updates authorization/flags example to TransactionBuilder + SetOptionsOperation.builder() and adds base fee/timeout. |
| docs/learn/fundamentals/contract-development/contract-interactions/stellar-transaction.mdx | Updates Soroban Java imports/throws to new exception + operation packages. |
| docs/build/guides/transactions/invoke-contract-tx-sdk.mdx | Updates Soroban Java imports/throws to new exception + operation packages. |
| docs/build/guides/transactions/create-account.mdx | Updates CreateAccount + asset helper usage for v3.1.0 (builder API + createNonNativeAsset). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Preview is available here: |
Addresses review feedback: this file was missed in the initial audit and still used the pre-1.0.0 API. Migrated the SetOptions/home-domain snippet: `new Transaction.Builder(...)` -> `new TransactionBuilder(...)` (with the now-required base fee/timeout), and nested `new SetOptionsOperation.Builder().setHomeDomain(...)` -> Lombok `SetOptionsOperation.builder().homeDomain(...)`. Verified via a full docs/ sweep that no other Java example still uses the old Transaction.Builder / *Operation.Builder / setSourceAccount API. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- create-account.mdx: `Asset.createNonNativeAsset(...)` returns `org.stellar.sdk.Asset`, and USDC is a 4-char code, so the `AssetTypeCreditAlphaNum12` declaration was both wrong and wouldn't compile (narrowing from `Asset`). Typed the variable as `Asset`, which is also what the `getTrustlineBalance` helper accepts. - how-to-issue-an-asset.mdx: the PaymentOperation "chaining" short-hand left `addOperation(...)` unclosed and the operation un-built; closed the operation with `.build()` and balanced the parentheses. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
Contributor
|
Found a small runtime bug while testing this against SDK 3.1.0: the new SetTrustlineFlagsOperation example in how-to-issue-an-asset.mdx only sets setFlags, but clearFlags is also @nonnull in the SDK, so build() throws NullPointerException: clearFlags is marked non-null but is null. Adding .clearFlags(EnumSet.noneOf(TrustLineFlags.class)) fixes it (verified by compiling and running the snippet against the real 3.1.0 jar). After fixing that(feel free to confirm it though!), LGTM! Approving just in case |
kaankacar
self-requested a review
July 21, 2026 15:24
kaankacar
approved these changes
Jul 21, 2026
Both setFlags and clearFlags are @nonnull on the SetTrustlineFlagsOperation @SuperBuilder in v3.1.0, so building with only setFlags throws NullPointerException at build(). Pass an explicit empty clearFlags set. Reported by @kaankacar, verified against the 3.1.0 source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Confirmed and fixed in e8f2f90. Verified against the v3.1.0 source: both Applied your suggested fix, passing an explicit empty set: .setFlags(EnumSet.of(TrustLineFlags.AUTHORIZED_FLAG))
.clearFlags(EnumSet.noneOf(TrustLineFlags.class))
.build())It's the only |
|
Preview is available here: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updating the Java code examples to the most up-to-date version of the SDK available (
v3.1.0at time of writing)