From a0bd3128f2af634f3523d307b85f56c12ec52f7d Mon Sep 17 00:00:00 2001 From: Dmytro Kozhevin Date: Mon, 10 Jun 2024 12:51:52 -0400 Subject: [PATCH 1/4] Updated the docs for extend/restore footprint ops. Extend TTL doc was incorrect, and restore doc lacked some important details. --- src/operations/extend_footprint_ttl.js | 25 +++++++++++++++++-------- src/operations/restore_footprint.js | 10 +++++++--- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/src/operations/extend_footprint_ttl.js b/src/operations/extend_footprint_ttl.js index 7e03f33e..94782001 100644 --- a/src/operations/extend_footprint_ttl.js +++ b/src/operations/extend_footprint_ttl.js @@ -1,21 +1,30 @@ import xdr from '../xdr'; /** - * Builds an operation to bump the time-to-live of a footprint (read and written - * ledger keys). Its only parameter is the new, absolute ledger sequence number - * at which the entry will expire. + * Builds an operation to bump the time-to-live (TTL) of the ledger keys. The + * keys for extension have to be provided in the read-only footprint of + * the transaction. + * + * The only parameter of the operation itself is the new minimum TTL for + * all the provided entries. If an entry already has a higher TTL, than it + * will just be skipped. * - * The footprint itself is derived from the transaction (see + * TTL is the number of ledgers from the current ledger (exclusive) until + * the last ledger the entry is still considered alive (inclusive). Thus + * the exact ledger until the entries will live will only be determined + * when transaction has been applied. + * + * The footprint has to be specified in the transaction. See * {@link TransactionBuilder}'s `opts.sorobanData` parameter, which is a * {@link xdr.SorobanTransactionData} instance that contains fee data & resource - * usage as part of {@link xdr.SorobanResources}). + * usage as part of {@link xdr.SorobanResources}. * * @function * @alias Operation.extendFootprintTtl * * @param {object} opts - object holding operation parameters - * @param {number} opts.extendTo - the absolute ledger sequence number at which - * the transaction's ledger keys will now expire + * @param {number} opts.extendTo - the minimum TTL that all the entries in + * the read-only footprint will have * @param {string} [opts.source] - an optional source account * * @returns {xdr.Operation} an Extend Footprint TTL operation @@ -23,7 +32,7 @@ import xdr from '../xdr'; */ export function extendFootprintTtl(opts) { if ((opts.extendTo ?? -1) <= 0) { - throw new RangeError("extendTo isn't a ledger quantity (uint32)"); + throw new RangeError("extendTo has to be positive"); } const extendFootprintOp = new xdr.ExtendFootprintTtlOp({ diff --git a/src/operations/restore_footprint.js b/src/operations/restore_footprint.js index b13b5a88..1f1c48e2 100644 --- a/src/operations/restore_footprint.js +++ b/src/operations/restore_footprint.js @@ -1,14 +1,18 @@ import xdr from '../xdr'; /** - * Builds a footprint restoration operation. + * Builds an operation to restore the archived ledger entries specified + * by the ledger keys. * + * The ledger keys to restore are specified separately from the operation + * in read-write footprint of the transaction. + * * It takes no parameters because the relevant footprint is derived from the - * transaction itself (see {@link TransactionBuilder}'s `opts.sorobanData` + * transaction itself. See {@link TransactionBuilder}'s `opts.sorobanData` * parameter (or {@link TransactionBuilder.setSorobanData} / * {@link TransactionBuilder.setLedgerKeys}), which is a * {@link xdr.SorobanTransactionData} instance that contains fee data & resource - * usage as part of {@link xdr.SorobanTransactionData}). + * usage as part of {@link xdr.SorobanTransactionData}. * * @function * @alias Operation.restoreFootprint From adc706a380bcaa0bcf8a84c4ef48d809342e230d Mon Sep 17 00:00:00 2001 From: Dmytro Kozhevin Date: Mon, 10 Jun 2024 12:56:18 -0400 Subject: [PATCH 2/4] !fixup assertion fix --- test/unit/operations/extend_restore_test.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/unit/operations/extend_restore_test.js b/test/unit/operations/extend_restore_test.js index 4e96b9b0..eb990a49 100644 --- a/test/unit/operations/extend_restore_test.js +++ b/test/unit/operations/extend_restore_test.js @@ -14,7 +14,7 @@ describe('Operation', function () { expect(() => { StellarBase.Operation.extendFootprintTtl({ extendTo: 0 }); - }).to.throw(/ledger quantity/i); + }).to.throw(/has to be positive/i); }); }); From 11ca9c84354c6ad79b1c2396bf6a5403f74fa3fa Mon Sep 17 00:00:00 2001 From: Dmytro Kozhevin Date: Mon, 10 Jun 2024 13:00:23 -0400 Subject: [PATCH 3/4] !fixup format --- src/operations/extend_footprint_ttl.js | 8 ++++---- src/operations/restore_footprint.js | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/operations/extend_footprint_ttl.js b/src/operations/extend_footprint_ttl.js index 94782001..cc3e8e3a 100644 --- a/src/operations/extend_footprint_ttl.js +++ b/src/operations/extend_footprint_ttl.js @@ -4,16 +4,16 @@ import xdr from '../xdr'; * Builds an operation to bump the time-to-live (TTL) of the ledger keys. The * keys for extension have to be provided in the read-only footprint of * the transaction. - * + * * The only parameter of the operation itself is the new minimum TTL for - * all the provided entries. If an entry already has a higher TTL, than it + * all the provided entries. If an entry already has a higher TTL, than it * will just be skipped. * * TTL is the number of ledgers from the current ledger (exclusive) until * the last ledger the entry is still considered alive (inclusive). Thus * the exact ledger until the entries will live will only be determined * when transaction has been applied. - * + * * The footprint has to be specified in the transaction. See * {@link TransactionBuilder}'s `opts.sorobanData` parameter, which is a * {@link xdr.SorobanTransactionData} instance that contains fee data & resource @@ -32,7 +32,7 @@ import xdr from '../xdr'; */ export function extendFootprintTtl(opts) { if ((opts.extendTo ?? -1) <= 0) { - throw new RangeError("extendTo has to be positive"); + throw new RangeError('extendTo has to be positive'); } const extendFootprintOp = new xdr.ExtendFootprintTtlOp({ diff --git a/src/operations/restore_footprint.js b/src/operations/restore_footprint.js index 1f1c48e2..b16527ec 100644 --- a/src/operations/restore_footprint.js +++ b/src/operations/restore_footprint.js @@ -4,9 +4,9 @@ import xdr from '../xdr'; * Builds an operation to restore the archived ledger entries specified * by the ledger keys. * - * The ledger keys to restore are specified separately from the operation + * The ledger keys to restore are specified separately from the operation * in read-write footprint of the transaction. - * + * * It takes no parameters because the relevant footprint is derived from the * transaction itself. See {@link TransactionBuilder}'s `opts.sorobanData` * parameter (or {@link TransactionBuilder.setSorobanData} / From 9ff9f441cd96d87958aedea9b4c1ca0ec33c472a Mon Sep 17 00:00:00 2001 From: Dmytro Kozhevin Date: Mon, 10 Jun 2024 13:11:48 -0400 Subject: [PATCH 4/4] !fixup typo --- src/operations/extend_footprint_ttl.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operations/extend_footprint_ttl.js b/src/operations/extend_footprint_ttl.js index cc3e8e3a..db7daae8 100644 --- a/src/operations/extend_footprint_ttl.js +++ b/src/operations/extend_footprint_ttl.js @@ -6,7 +6,7 @@ import xdr from '../xdr'; * the transaction. * * The only parameter of the operation itself is the new minimum TTL for - * all the provided entries. If an entry already has a higher TTL, than it + * all the provided entries. If an entry already has a higher TTL, then it * will just be skipped. * * TTL is the number of ledgers from the current ledger (exclusive) until