Proposal: Rename extendFootprintTtl.extendTo to minimumTtl for clarity

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Breaking Changes
+* `Operation.extendFootprintTtl`'s `extendTo` field is now named `minimumTtl` for clarity: the value is a quantity of ledgers relative to the last-closed ledger.
+
 
 ## [`v11.1.0`](https://github.com/stellar/js-stellar-base/compare/v11.0.1...v11.1.0)
 

src/operation.js

@@ -383,7 +383,7 @@ export class Operation {
       }
       case 'extendFootprintTtl': {
         result.type = 'extendFootprintTtl';
-        result.extendTo = attrs.extendTo();
+        result.minimumTtl = attrs.extendTo();
         break;
       }
       case 'restoreFootprint': {

src/operations/extend_footprint_ttl.js

@@ -2,8 +2,9 @@ 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.
+ * ledger keys). Its only parameter is the number of ledgers (N) **relative** to
+ * the last-closed ledger (LCL) at which the entry will be archived, i.e. it
+ * will be archived at a ledger >= LCL+N. These are the entries' time to live.
  *
  * The footprint itself is derived from the transaction (see
  * {@link TransactionBuilder}'s `opts.sorobanData` parameter, which is a
@@ -14,21 +15,22 @@ import xdr from '../xdr';
  * @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.minimumTtl - the number of ledgers relative to the
+ *    last-closed ledger that the footprint entry should live for (note that
+ *    this value has to be below the network's `max_entry_ttl` setting)
  * @param {string} [opts.source] - an optional source account
  *
  * @returns {xdr.Operation} an Extend Footprint TTL operation
  *    (xdr.ExtendFootprintTTLOp)
  */
 export function extendFootprintTtl(opts) {
-  if ((opts.extendTo ?? -1) <= 0) {
-    throw new RangeError("extendTo isn't a ledger quantity (uint32)");
+  if ((opts.minimumTtl ?? -1) <= 0) {
+    throw new RangeError("minimumTtl isn't a ledger quantity (uint32)");
   }
 
   const extendFootprintOp = new xdr.ExtendFootprintTtlOp({
     ext: new xdr.ExtensionPoint(0),
-    extendTo: opts.extendTo
+    extendTo: opts.minimumTtl
   });
 
   const opAttributes = {

test/unit/operations/extend_restore_test.js

@@ -3,17 +3,17 @@ const { Operation } = StellarBase;
 describe('Operation', function () {
   describe('.extendFootprintTtl()', function () {
     it('creates operation', function () {
-      const op = StellarBase.Operation.extendFootprintTtl({ extendTo: 1234 });
+      const op = StellarBase.Operation.extendFootprintTtl({ minimumTtl: 1234 });
       const xdr = op.toXDR('hex');
       const operation = StellarBase.xdr.Operation.fromXDR(xdr, 'hex');
 
       expect(operation.body().switch().name).to.equal('extendFootprintTtl');
       const obj = StellarBase.Operation.fromXDRObject(operation);
       expect(obj.type).to.be.equal('extendFootprintTtl');
-      expect(obj.extendTo).to.equal(1234);
+      expect(obj.minimumTtl).to.equal(1234);
 
       expect(() => {
-        StellarBase.Operation.extendFootprintTtl({ extendTo: 0 });
+        StellarBase.Operation.extendFootprintTtl({ minimumTtl: 0 });
       }).to.throw(/ledger quantity/i);
     });
   });

types/index.d.ts

@@ -571,7 +571,7 @@ export namespace OperationOptions {
   }
 
   interface ExtendFootprintTTL extends BaseOptions {
-    extendTo: number;
+    minimumTtl: number;
   }
   type RestoreFootprint = BaseOptions;
 }
@@ -904,7 +904,7 @@ export namespace Operation {
     options: OperationOptions.ExtendFootprintTTL
   ): xdr.Operation<ExtendFootprintTTL>;
   interface ExtendFootprintTTL extends BaseOperation<OperationType.ExtendFootprintTTL> {
-    extendTo: number;
+    minimumTtl: number;
   }
 
   function restoreFootprint(options: OperationOptions.RestoreFootprint):