Correct Soroban transaction resource, TTL, and SAC XDR references - #2655
Conversation
Fixes three Raven-reported drifts in Soroban transaction/XDR reference docs, verified against current stellar-xdr (curr) and stellar-core behavior. #2596 — transaction resource field names: - SorobanResources uses diskReadBytes (not readBytes); SorobanTransactionData uses resourceFee with the ext union first (not refundableFee + ExtensionPoint) - fixes the runtime-broken JS restoration example (readBytes / ExtensionPoint) - sweeps prose in state-archival and fees-resource-limits-metering #2597 — ExtendFootprintTTLOp extends every read-only footprint entry; the real constraint is one shared extendTo, not one key per transaction. #2613 — current XDR enums: CONTRACT_EXECUTABLE_STELLAR_ASSET, CONTRACT_ID_PREIMAGE_FROM_ASSET, ENVELOPE_TYPE_CONTRACT_ID; issuer is only the initial (mutable) SAC administrator. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates Soroban resource, TTL, and SAC documentation to current XDR terminology and behavior.
Changes:
- Renames obsolete resource and SAC XDR fields.
- Corrects multi-entry TTL-extension guidance.
- Clarifies mutable SAC administration.
Blocking findings include a still-unusable restoration example, contradictory TTL example, stale XDR link, and incomplete resolution of issues #2596 and #2613.
Recommendation: NEEDS-CHANGES — Address the stored review comments.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
docs/tokens/stellar-asset-contract.mdx |
Updates SAC XDR and administrator terminology. |
docs/learn/fundamentals/fees-resource-limits-metering.mdx |
Renames the declared resource-fee field. |
docs/learn/fundamentals/contract-development/storage/state-archival.mdx |
Renames the disk-read resource field. |
docs/learn/fundamentals/contract-development/contract-interactions/stellar-transaction.mdx |
Updates current transaction and SAC XDR layouts. |
docs/build/guides/archival/extend-persistent-entry-js.mdx |
Revises multi-entry TTL guidance. |
docs/build/guides/archival/create-restoration-footprint-js.mdx |
Updates JavaScript XDR construction. |
|
Preview is available here: |
- extend-persistent-entry: replace the two-transaction split with a real single-operation combined-footprint example (setReadOnly([entry, footprint])) so it matches the corrected multi-key/same-target guidance (#2597) - create-restoration-footprint: add a caution that the zeroed diskReadBytes/ writeBytes/resourceFee are placeholders and a real restore must populate them via simulation or it fails with RESTORE_FOOTPRINT_RESOURCE_LIMIT_EXCEEDED - stellar-asset-contract: repoint the stale pinned [contract_id] link to the current XDR (curr); add SAC on-chain identification guidance (SCContractInstance.executable == CONTRACT_EXECUTABLE_STELLAR_ASSET, name()/symbol() after verification, provenance limits) - fees-resource-limits-metering: distinguish the pre-apply declared-resourceFee check from apply-time refundable metering - state-archival: soften diskReadBytes wording to "serialized size" Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (5)
docs/build/guides/archival/extend-persistent-entry-js.mdx:159
- The suggested different-target example cannot be followed: both helpers above hard-code
extendTo: 100_000and neither accepts anextendToargument. Readers cannot call them “with differentextendTovalues” without first changing their signatures, so either parameterize the helpers or state that requirement here.
If the entries instead need _different_ target TTLs, extend each in its own transaction — for example by calling the single-entry `extendPersistentEntryTTL` and `extendContractCodeTTL` helpers above with different `extendTo` values.
docs/build/guides/archival/extend-persistent-entry-js.mdx:129
LedgerKey.contractDataexpects anxdr.LedgerKeyContractDatavalue, not a plain object. The SDK’s ownContract.getFootprint()constructs this arm withnew xdr.LedgerKeyContractData(...); as written, serialization/preparation of this new example will fail when the union tries to encode the object. Wrap these fields in the generated struct constructor.
const persistentEntry = new StellarSdk.xdr.LedgerKey.contractData({
contract: StellarSdk.Address.fromString(contractId).toScAddress(),
key: StellarSdk.xdr.ScVal.scvSymbol(storageKey),
durability: StellarSdk.xdr.ContractDataDurability.persistent(),
});
docs/learn/fundamentals/contract-development/contract-interactions/stellar-transaction.mdx:615
- The updated Protocol 23+ structure is still sourced by the
[extension]link above, but that pinnedc2e702csnapshot defines the oldreadBytes/refundableFeelayout this PR is correcting. Repoint that reference to the current XDR (preferably a current pinned commit), otherwise readers following the citation see a structure that directly contradicts this block.
// The maximum number of bytes this transaction can read from disk backed entries
uint32 diskReadBytes;
// The maximum number of bytes this transaction can write to ledger
uint32 writeBytes;
};
docs/learn/fundamentals/contract-development/contract-interactions/stellar-transaction.mdx:640
- This description now omits the
extfield immediately shown above. In the current layout it is no longer just an empty extension point: version 1 carriesSorobanResourcesExtV0.archivedSorobanEntries, which controls automatic restoration metadata. Include that third component so the prose matches the updated XDR.
This data comprises the Soroban `resources` and the `resourceFee`. The `resourceFee` is the portion of the transaction fee allocated to Soroban resource fees. It has a non-refundable part (fees for instructions, ledger I/O, and transaction size) and a refundable part that is charged based on actual consumption of refundable resources: the contract events emitted by the transaction, the return value of the host function invocation, and the [ledger space rent](../storage/state-archival.mdx).
docs/build/guides/archival/create-restoration-footprint-js.mdx:75
- The walkthrough still describes this as an “extension point for future use,” but
SorobanTransactionDataExtalready has a live version-1 arm containingSorobanResourcesExtV0.archivedSorobanEntriesfor automatic restoration. Setting version 0 is valid for this manual restore, but the explanation should say that rather than claiming the extension is unused.
ext: new xdr.SorobanTransactionDataExt(0),
kaankacar
left a comment
kaankacar
left a comment
There was a problem hiding this comment.
One question on the new multi-key example: when I tried running it against @stellar/stellar-sdk 16.2.0 (current latest), transaction.setSorobanData(...) threw a TypeError for me, since the built Transaction doesn't seem to have that method (it looks like it lives on TransactionBuilder instead). Same with new xdr.LedgerKey.contractData({...}) taking a plain object, it fails at serialization unless wrapped in new xdr.LedgerKeyContractData({...}).
Am I holding it wrong, or would this trip up someone copy-pasting the example? I notice the page's existing helpers use the same patterns, so maybe it predates this PR and is better handled as a follow-up.
Otherwise LGTM, happy to merge once we settle this.
|
Preview is available here: |
|
@kaankacar you weren't wrong. there was some buggy stuff in there, even some pre-existing weirdness. should be all fixed now. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (3)
docs/learn/fundamentals/contract-development/contract-interactions/stellar-transaction.mdx:612
- The source link immediately above this block still targets the old
c2e702…XDR snapshot that backed the removedreadBytes/refundableFeelayout. As a result, the updateddiskReadBytesdefinition no longer matches its cited reference. Point the link at current XDR (ideally a current pinned commit).
// The maximum number of bytes this transaction can read from disk backed entries
uint32 diskReadBytes;
docs/build/guides/archival/extend-persistent-entry-js.mdx:12
- This conflates TTL with
liveUntilLedger. TTL is the number of ledgers remaining until an entry stops being live; the absolute last ledger is the entry'sliveUntilLedger(as defined indocs/learn/fundamentals/contract-development/storage/state-archival.mdx:108). This distinction matters becauseextendTois a relative TTL offset, not an absolute ledger sequence.
- a Time To Live (TTL), which is the last ledger through which the entry stays live.
docs/build/guides/archival/extend-persistent-entry-js.mdx:272
- The suggested calls cannot supply different targets: all three helpers hard-code
extendTo: 100_000and have noextendToparameter. Readers following this example therefore cannot implement the different-target case described here without first changing the helpers.
That shared `extendTo` is the one real constraint. Entries that need _different_ target TTLs can't share an operation, so extend each one in its own transaction (for example, by calling the `extendPersistentEntryTTL`, `extendContractInstanceTTL`, and `extendContractCodeTTL` helpers above with different `extendTo` values).
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
- fix stale XDR link - clarify ttl and liveUntilLedger conflated descriptions - note what the helper functions actually do for variable values
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
Batch fix for three Raven-reported drifts in the Soroban transaction/XDR reference docs. All claims verified against current
stellar-xdr(curr) and stellar-core behavior before editing.Changes
Transaction resource field names (#2596)
Protocol 23+ renamed the resource fields, but the reference docs still used the old names — and one example was runtime-broken as a result.
stellar-transaction.mdx—SorobanResourcesnow usesdiskReadBytes(wasreadBytes);SorobanTransactionDatanow shows the current layout: theextunion first, thenresources, thenresourceFee(wasrefundableFee+ a trailingExtensionPoint). Added the referencedSorobanResourcesExtV0so the block is self-contained. Prose updated to match.create-restoration-footprint-js.mdx— the JS example constructedxdr.SorobanResources({... readBytes ...})andext: new xdr.ExtensionPoint(0), which throws at serialization against currentjs-stellar-base. Now usesdiskReadBytesandxdr.SorobanTransactionDataExt(0). Walkthrough bullet updated.state-archival.mdx,fees-resource-limits-metering.mdx— swept the same stalereadBytes/refundableFeeprose references.(The issue's "enforcement phases" half cites no concrete wrong sentence, so that speculative rewrite is intentionally out of scope.)
Multi-entry
ExtendFootprintTTLOpguidance (#2597)extend-persistent-entry-js.mdxclaimed you "cannot combine extensions for different ledger entries in a single transaction." CurrentExtendFootprintTTLOpFrameiterates every entry in the read-only footprint. The real constraint is the single sharedextendTooffset — entries needing different targets are what require separate operations/transactions. Reworded to match; the existing two-transaction example is now framed as the different-target case.SAC executable identity XDR terminology (#2613)
Design-era XDR names in
stellar-transaction.mdxandstellar-asset-contract.mdxno longer matchstellar-xdr:CONTRACT_EXECUTABLE_TOKEN→CONTRACT_EXECUTABLE_STELLAR_ASSETCONTRACT_ID_FROM_ASSET→CONTRACT_ID_PREIMAGE_FROM_ASSETHashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET→HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID(theFROM_ASSETpreimage now nests under it)Also qualified the issuer/admin relationship: the asset issuer is only the initial administrator, and authority is mutable via
set_admin.Closes #2596
Closes #2597
Closes #2613
🤖 Generated with Claude Code