Add support for LEDGER_ENTRY_RESTORE

[tamirms]

Protocol 23 will introduce a new ledger entry change type called LEDGER_ENTRY_RESTORE

When an entry is restored, a new type of LedgerEntryChange is emitted: LedgerEntryChangeType = LEDGER_ENTRY_RESTORE. The entire ingestion stack will need to be able to understand the semantics of this new change.

The ingestion library will need to support LEDGER_ENTRY_RESTORE because it currently returns an error when encountering an unknown change type. Horizon ingestion should interpret a LEDGER_ENTRY_RESTORE change in the same way as LEDGER_ENTRY_CREATED because the two are functionally equivalent.

[urvisavla]

With the introduction of RESTORE entry type, we need to update the change compactor logic accordingly. The new logic should support two different types of RESTORE entries :

• Archived: these entries will have both a state change type entry and a restore change type entry in the ledger (TTL type entries).
• Evicted: these entries only have a restore change type entry in the ledger.

The change compactor must handle these two types differently. Here is the original algorithm for the change compactor and the following the proposed algorithm that incorporates the RESTORE change type.

//
//  1. If the change is CREATED it checks if any change connected to given entry
//     is already in the cache. If not, it adds CREATED change. Otherwise, if
//     existing change is
//     a. CREATED: return an error because we can't add an entry that already exists.
//     b. UPDATED: return an error because we can't add an entry that already exists.
//     c. REMOVED: entry exists in the DB but was marked for removal; change the type
//     to UPDATED and update the new value.
//     d. RESTORED: return an error as the RESTORED change indicates the entry already
//     exists.
//
//  2. If the change is UPDATE it checks if any change connected to given entry
//     is already in the cache. If not, it adds UPDATE change. Otherwise, if
//     existing change is
//     a. CREATED: We want to create this in a DB which means that it doesn't exist
//     in a DB so we need to update the entry but stay with CREATED type.
//     b. UPDATED: update it with the new value.
//     c. REMOVED it means that at this point in the ledger the entry is removed
//     so updating it returns an error.
//     d. RESTORED: update it with the new value but keep the type as RESTORED.
//
//  3. If the change is REMOVED, it checks if any change related to the given entry
//     already exists in the cache. If not, it adds the `REMOVED` change. Otherwise,
//     if existing change is
//     a. CREATED: due to previous transitions we want to create
//     this in a DB which means that it doesn't exist in a DB. If it was created and
//     removed in the same ledger it's a noop so we remove the entry from the cache.
//     b. UPDATED: update it to be a REMOVE change because the UPDATE change means
//     the entry exists in a DB.
//     c. REMOVED: return an error because we can't remove an entry that was already
//     removed.
//     d. RESTORED: if the item was previously restored from an archived state, it means
//     it already exists in the DB, so change it to REMOVED type. If the restored item
//     was evicted, it doesn't exist in the DB, so it's a noop so remove the entry from
//     the cache.
//
//  4. If the change is RESTORED for an **evicted** entry (pre is nil), it checks if any
//     change related to the given entry already exists in the cache. If not, it adds
//     the RESTORED change. Otherwise, if existing change is
//     a. CREATED: return an error because we can't restore and entry that already exists.
//     b. UPDATED: return an error because we can't restore an entry that already exists.
//     c. REMOVED: entry exists in the DB but was marked for removal; change the
//     type to RESTORED and update the new value.
//     d. RESTORED: return an error as the RESTORED change indicates the entry
//     already exists.
//
//  5. If the change is RESTORED for an **archived** entry (pre and post not nil), it checks
//     if any change related to the given entry already exists in the cache. If not,
//     it adds the RESTORED change. Otherwise, if existing change is
//     a. CREATED: it means that it doesn't exist in the DB so we need to update the
//     entry but stay with CREATED type.
//     b. UPDATED: update it with the new value and change the type to RESTORED.
//     c. REMOVED: return an error because we can not RESTORE an entry that was already
//     removed.
//     d. RESTORED: update it with the new value.