File Lifecycle

Every file in Tusky moves through a storage pipeline — from fast hot cache to durable decentralized storage on the Walrus network.

The pipeline

1. Upload → hot

When you upload a file, it goes to the hot cache (S3-compatible object storage). It’s immediately available for download at full speed.

2. Walrus sync → synced

A background worker picks up the file and publishes it to the Walrus decentralized storage network. This typically takes seconds to a few minutes. Once confirmed, the status changes to synced.

The file now exists in two places: hot cache (fast) and Walrus (durable). Two identifiers are stored:

• walrusBlobId — content-addressed hash for retrieval
• walrusBlobObjectId — Sui object ID for epoch renewals

3. Hot eviction → cold

After the hot retention period expires, the hot eviction worker removes the file from the hot cache. The file is now cold — stored only on Walrus.

Note

Files are never evicted unless walrusBlobId is confirmed. Tusky will not remove a file from hot cache without a verified Walrus copy.

4. Rehydration → back to hot

When a cold file is needed, Tusky fetches it from Walrus back to the hot cache:

TypeScript

// Trigger rehydration
await tusky.files.rehydrate(file.id);

// Wait for it to be available
const rehydrated = await tusky.files.waitForStatus(file.id, ['hot', 'synced']);

Python

# Trigger rehydration
requests.post(
    f"https://api.opentusk.ai/api/files/{file_id}/rehydrate",
    headers=headers,
)

# Poll until hot
import time
while True:
    resp = requests.get(f"https://api.opentusk.ai/api/files/{file_id}", headers=headers)
    if resp.json()["status"] in ("hot", "synced"):
        break
    time.sleep(2)

Walrus epochs

Walrus stores data for a set number of epochs (each ~24 hours). Tusky automatically renews epoch leases before they expire to prevent data loss.

The walrusRenew background worker:

1. Scans for files approaching epoch expiry
2. Calls extendBlob() via the Walrus SDK using the walrusBlobObjectId
3. Pays WAL tokens to extend the storage lease

Caution

Epoch renewal failures are critical. If an epoch expires without renewal, the data is garbage collected permanently by the Walrus network.

Error handling

If Walrus sync fails after retries, the file status is set to error. The file remains in the hot cache and is safe — it just hasn’t been durably stored on Walrus yet.

Monitor errors via webhooks (file.error event) or by listing files filtered by status.

Summary

Status	Hot cache	Walrus	Available
uploading	Pending	No	No
hot	Yes	No	Yes (fast)
synced	Yes	Yes	Yes (fast)
cold	No	Yes	After rehydration
error	Yes	Failed	Yes (fast)