add guide for extending a persistent entry and contract using the javascript sdk

docs/build/guides/archival/extend-persistent-entry-js.mdx

@@ -0,0 +1,179 @@
+---
+title: Extend a persistent entry and contract using the JavaScript SDK
+description: How to extend a persistent entry and contract using the JavaScript SDK
+---
+
+Persistent storage is used for storing data and contracts that need to remain on the network for a long period.
+
+Each entry made to the persistent storage is stored as a key-value store. An entry consists of:
+
+- A key (identifier for the data)
+- A value (the data itself)
+- A Time-To-Live (TTL) that determines how long the data remains on the network
+
+When the TTL expires, the data is then archived on the network and is no longer accessible unless it is unarchived. To prevent data and contracts from being inaccessible, the TTL can be extended before it expires.
+
+## Extension Process
+
+1. Create the identifier according to what you're extending:
+
+- For a persistent entry, specify the contract address, storage key, and durability type (persistent)
+- For contract code, specify the contract ID
+
+2. Create a footprint and declare which storage locations will be extended and include the identifier for persistent entry, contract code, or both, depending on your intent.
+
+3. Build and submit the transaction:
+
+- Add the `extendFootprintTtl` operation with your intended TTL
+- Sign and submit the transaction
+
+:::note TTL can only be extended by the deployer or an authorized account. :::
+
+### Extending a persistent entry
+
+```javascript
+const StellarSdk = require("@stellar/stellar-sdk");
+const { Server } = require("@stellar/stellar-sdk/rpc");
+
+async function extendPersistentEntryTTL(contractId, storageKey, sourceKeypair) {
+  const server = new Server("https://soroban-testnet.stellar.org");
+  const account = await server.getAccount(sourceKeypair.publicKey());
+  const fee = "200100";
+
+  // Create an identifier for the entry
+  const persistentEntry = new StellarSdk.xdr.LedgerKey.contractData({
+    contract: StellarSdk.Address.fromString(contractId).toScAddress(),
+    key: StellarSdk.xdr.ScVal.scvSymbol(storageKey),
+    durability: StellarSdk.xdr.ContractDataDurability.persistent(),
+  });
+
+  // Create footprint for the entry
+  const footprint = new StellarSdk.xdr.LedgerFootprint({
+    readOnly: [],
+    readWrite: [persistentEntry],
+  });
+
+  // build and submit the transaction
+  const transaction = new StellarSdk.TransactionBuilder(account, {
+    fee,
+    networkPassphrase: StellarSdk.Networks.TESTNET,
+  })
+    .addOperation(
+      StellarSdk.Operation.extendFootprintTtl({
+        extendTo: 500_000,
+        footprint: footprint,
+      }),
+    )
+    .setTimeout(30)
+    .build();
+
+  transaction.sign(sourceKeypair);
+  return await server.sendTransaction(transaction);
+}
+```
+
+### Extending the contract code
+
+```javascript
+const StellarSdk = require("@stellar/stellar-sdk");
+const { Server } = require("@stellar/stellar-sdk/rpc");
+
+async function extendContractCodeTTL(contractId, sourceKeypair) {
+  const server = new Server("https://soroban-testnet.stellar.org");
+  const account = await server.getAccount(sourceKeypair.publicKey());
+  const fee = "200100";
+
+  // Create the contract code identifier
+  const contractHash = new StellarSdk.xdr.LedgerKey.contractCode({
+    hash: StellarSdk.Address.fromString(contractId).toScAddress(),
+  });
+
+  // Create footprint for contract code
+  const footprint = new StellarSdk.xdr.LedgerFootprint({
+    readOnly: [],
+    readWrite: [contractHash],
+  });
+
+  // build and submit the transaction
+  const transaction = new StellarSdk.TransactionBuilder(account, {
+    fee,
+    networkPassphrase: StellarSdk.Networks.TESTNET,
+  })
+    .addOperation(
+      StellarSdk.Operation.extendFootprintTtl({
+        extendTo: 500_000,
+        footprint: footprint,
+      }),
+    )
+    .setTimeout(30)
+    .build();
+
+  transaction.sign(sourceKeypair);
+  return await server.sendTransaction(transaction);
+}
+```
+
+### Extending both the contract and a persistent entry
+
+```javascript
+const StellarSdk = require("@stellar/stellar-sdk");
+const { Server } = require("@stellar/stellar-sdk/rpc");
+
+async function extendContractAndPersistentEntry(
+  contractId,
+  storageKey,
+  sourceKeypair,
+) {
+  const server = new Server("https://soroban-testnet.stellar.org");
+  const account = await server.getAccount(sourceKeypair.publicKey());
+  const fee = "200100";
+
+  // Create both identifiers
+  const contractHash = new StellarSdk.xdr.LedgerKey.contractCode({
+    hash: StellarSdk.Address.fromString(contractId).toScAddress(),
+  });
+
+  const persistentEntry = new StellarSdk.xdr.LedgerKey.contractData({
+    contract: StellarSdk.Address.fromString(contractId).toScAddress(),
+    key: StellarSdk.xdr.ScVal.scvSymbol(storageKey),
+    durability: StellarSdk.xdr.ContractDataDurability.persistent(),
+  });
+
+  // Create footprint with both identifiers
+  const footprint = new StellarSdk.xdr.LedgerFootprint({
+    readOnly: [],
+    readWrite: [contractHash, persistentEntry],
+  });
+
+  // build and submit the transaction
+  const transaction = new StellarSdk.TransactionBuilder(account, {
+    fee,
+    networkPassphrase: StellarSdk.Networks.TESTNET,
+  })
+    .addOperation(
+      StellarSdk.Operation.extendFootprintTtl({
+        extendTo: 500_000,
+        footprint: footprint,
+      }),
+    )
+    .setTimeout(30)
+    .build();
+
+  transaction.sign(sourceKeypair);
+  return await server.sendTransaction(transaction);
+}
+```
+
+Usage example:
+
+```javascript
+const contractId = "CBEE2DHGMYRKJKSJO5E55LBKFMPXE57ZWKTXTCRMC5ANIRJ7IW2Y2WVE";
+const storageKey = "BALANCE";
+const sourceKeypair = StellarSdk.Keypair.fromSecret(
+  "SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+);
+
+extendPersistentEntryTTL(contractId, storageKey, sourceKeypair)
+  .then((result) => console.log("Extension successful:", result))
+  .catch((error) => console.error("Extension failed:", error));
+```