[Bug]: listStorageKeys() returns the durability instead of the storage key (off-by-one) #87

Category: Bug | Difficulty: advanced

Suggested labels: bug, advanced, help wanted

Problem

ContractStateService.listStorageKeys() parses a Redis cache key back into its storage-key component but indexes the wrong array slot, so it returns the durability of every entry rather than the key.

src/modules/stellar/soroban/contract-state.service.ts:109-113:

// Extract just the storage key portion from the full cache key
return keys.map((key) => {
  const parts = key.split(':');
  return parts.length >= 4 ? parts[3] : key;
});

The key format built by cacheKey() is soroban:state:{contractId}:{durability}:{keyPart} (see contract-state.service.ts:225), which splits to:

So parts[3] is the durability string (persistent, temporary, ΓǪ), not the key.

Why it matters

This corrupts two consumers:

• exportContractState() (contract-state.service.ts:119-135) calls getState(contractId, key) with the durability, so it reads the wrong entries and produces a garbage export.
• ContractUpgradeManager.checkStateCompatibility() (contract-upgrade.manager.ts:196-239) diffs these "keys", so every real key looks removed and stateCompatible is effectively always false, which blocks legitimate upgrades.

It also silently discards the durability information that downstream consumers may need.

Suggested direction

1. Return both key and durability ΓÇö e.g. a StorageKeyRef { key: string; durability: string }[] ΓÇö or at minimum index parts[4].
2. Guard on parts.length >= 5 (not >= 4) and fall back to the full key when the shape is unexpected.
3. Prefer encoding the cache key with an unambiguous separator (or store a small JSON envelope) so parsing is not positional. Remember that listStorageKeys and invalidateContract both feed the keyPart into a Redis SCAN MATCH glob, so a : or * inside a key currently collides with other entries ΓÇö see contract-state.service.ts:154.
4. exportContractState() currently swallows errors with an empty catch { // Skip keys that fail to load } (:129-131). Log each failure at warn with the key so a partial export is diagnosable, and add a SCAN COUNT cap.
5. contract-state.service.spec.ts:96-103 only tests invalidateContract ΓÇö add coverage for listStorageKeys and exportContractState.

Acceptance criteria

• listStorageKeys() returns the actual storage key part (parts[4]) and the guard checks parts.length >= 5
• The returned type carries durability explicitly if that information is needed by callers
• exportContractState() returns keys that getState() can actually re-read
• Individual key-read failures are logged rather than silently skipped
• ContractUpgradeManager.checkStateCompatibility() reports stateCompatible: true for a contract whose key set is unchanged
• Unit tests cover listStorageKeys, exportContractState, and keys containing : / *
• Tests added/updated and passing
• Docs updated if behavior changes