Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

Commit

Permalink
Fixup headers: single # is hidden
Browse files Browse the repository at this point in the history
  • Loading branch information
Shaptic committed Jul 27, 2023
1 parent 5b49559 commit e97db91
Showing 1 changed file with 22 additions and 22 deletions.
44 changes: 22 additions & 22 deletions docs/fundamentals-and-concepts/state-expiration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,27 @@ title: State Expiration
description: State Expiration Semantics
---

# Terms and Semantics
## Terms and Semantics

## Expiration Ledger
### Expiration Ledger

Each `ContractData` and `ContractCode` entry has an `expirationLedger` field stored in its `LedgerEntry`.
The entry is considered expired when `current_ledger > expirationLedger`.

## Lifetime
### Lifetime

An entry's lifetime is defined as how many ledgers remain until the entry expires.
For example, if the current ledger is 5 and an entry's expiration ledger is 15, then
the entry's lifetime is 10 ledgers.

## Minimum Lifetime
### Minimum Lifetime

For each entry type, there is a minimum lifetime that the entry must have when being created
or updated. This lifetime minimum is enforced automatically at the protocol level. This minimum
is a network parameter and defaults to 16 ledgers for `Temporary` entries and 4,096 ledgers for
`Persistent` and `Instance` entries.

## Maximum Lifetime
### Maximum Lifetime

On any given ledger, an entry's lifetime can be extended up to the maximum lifetime. This is a
network parameter and defaults to 1 year worth of ledgers. This maximum lifetime is not enforced
Expand All @@ -33,11 +33,11 @@ created on January 1st, 2024, its lifetime could initially be bumped up to Janua
After this initial lifetime bump, if the entry received another lifetime bump later on January 10th, 2024,
the lifetime could be extended up to January 10th, 2025.

# Operations
## Operations

## BumpFootprintExpirationOp
### BumpFootprintExpirationOp

### Semantics
#### Semantics

XDR:

Expand Down Expand Up @@ -75,7 +75,7 @@ entry2 and entry3 will not be updated because they already have an
expirationLedger that is large enough.
```

### Transaction resources
#### Transaction resources

`BumpFootprintExpirationOp` is a Soroban operation, and therefore must be the
only operation in a transaction. The transaction also needs to populate
Expand All @@ -86,7 +86,7 @@ sure `readBytes` includes the key and entry size of every entry in the
`readOnly` set and make sure `extendedMetaDataSizeBytes` is at least double of
`readBytes`.

## RestoreFootprintOp
### RestoreFootprintOp

XDR:

Expand Down Expand Up @@ -115,7 +115,7 @@ they can be updated in the future through a validator vote.

[minimums]: https://github.com/stellar/stellar-core/blob/2109a168a895349f87b502ae3d182380b378fa47/src/ledger/NetworkConfig.h#L77-L78

### Transaction resources
#### Transaction resources

`RestoreFootprintOp` is a Soroban operation, and therefore must be the only
operation in a transaction. The transaction also needs to populate
Expand All @@ -128,11 +128,11 @@ sure `writeBytes` includes the key and entry size of every entry in the

---

# Examples
## Examples

We've done our best to build tooling around state expiration in the JavaScript SDK to make it easier to deal with, and this set of examples demonstrates how to leverage it.

## Overview
### Overview

Both restoring and bumping the expiration of ledger entries follows a multi-step process regardless of their nature (contract data, instances, etc.):

Expand All @@ -150,14 +150,14 @@ Each of the examples below will follow a structure like this. We'll work our way

Remember, though, that **any** combination of these scenarios can occur in reality.

## Preparation
### Preparation

To start off, we'll assume the following:

- you have created and funded account on the Soroban Futurenet
- you've built and deployed the `increment` contract from the [Soroban examples](https://github.com/stellar/soroban-examples/blob/main/increment/src/lib.rs) using that account

### Preamble
#### Preamble

In order to help the scaffolding of the code, we'll introduce some reusable components. The following is a simple, rudimentary looping mechanism to submit a transaction to Soroban RPC and wait for a result:

Expand Down Expand Up @@ -211,11 +211,11 @@ function sleep(ms: number) {

Remember: You should always handle errors gracefully! This is a fail hard and fail fast approach for the purposes of the examples.

## Examples
### Examples

Let's dive into some TypeScript.

### My data expired!
#### My data expired!

Let's start with the simplest, most-likely occurrence: my piece of persistent data expired off of the ledger because I haven't interacted with my contract in a while. How do I get it back?

Expand Down Expand Up @@ -272,7 +272,7 @@ function submitOrRestore(
//
const preppedTx = TransactionBuilder.cloneFrom(restoreTx)
.setSorobanData(simData)
.setLedgerKeys([], ledgerKeys)
.setFootprint([], ledgerKeys)
.build();
preppedTx.sign(signer);

Expand Down Expand Up @@ -304,7 +304,7 @@ async function buildRestoreTx(signer: Keypair, ...ledgerKeys: xdr.LedgerKey[]) {
networkPassphrase: Networks.FUTURENET,
})
.addOperation(op)
.setLedgerKeys([], ledgerKeys)
.setFootprint([], ledgerKeys)
.setTimeout(15)
.build();

Expand All @@ -317,7 +317,7 @@ async function buildRestoreTx(signer: Keypair, ...ledgerKeys: xdr.LedgerKey[]) {
}
```

### The contract itself expired!
#### The contract itself expired!

As you can imagine, if the ledger cannot find your deployed contract instance, it can't load it to execute your invocations.

Expand All @@ -339,6 +339,6 @@ We need **both** to stay on the ledger for our contract calls to work.

Let's work through how these can be recovered. They are slightly different for a convenient reason: we don't need simulation to figure out the footprints, though you still can do that.

#### My contract _code_ expired
##### My contract _code_ expired

#### My contract _instance_ expired
##### My contract _instance_ expired

0 comments on commit e97db91

Please sign in to comment.