File Statuses

Every file in Tusky has a status that reflects where it currently lives in the storage pipeline.

Status values

Status	Description
uploading	File upload initiated but not yet confirmed
hot	File confirmed and available in the hot cache (DO Spaces)
synced	File synced to Walrus network and still in hot cache
cold	File evicted from hot cache, stored only on Walrus
error	Sync or processing failed

Lifecycle diagram

                    ┌──────────┐
        upload      │          │    confirm
    ───────────────►│ uploading├──────────────┐
                    │          │              │
                    └──────────┘              ▼
                                        ┌─────────┐
                                        │         │
                                        │   hot   │
                                        │         │
                                        └────┬────┘
                                             │
                               walrus sync   │
                                             ▼
                                        ┌─────────┐
                                        │         │
                                        │ synced  │
                                        │         │
                                        └────┬────┘
                                             │
                             hot eviction    │
                                             ▼
                    ┌──────────┐        ┌─────────┐
                    │          │◄───────┤         │
                    │   hot    │rehydr. │  cold   │
                    │          ├───────►│         │
                    └──────────┘        └─────────┘

    Any state can transition to "error" if processing fails.

Key transitions

uploading → hot

Triggered when the client calls the confirm upload endpoint after successfully PUTting bytes to the presigned URL.

hot → synced

The background worker downloads the file from the hot cache and publishes it to the Walrus network. The file remains available in the hot cache.

synced → cold

The hot eviction worker removes the file from the hot cache once it’s safely on Walrus. This only happens if walrusBlobId is set — Tusky never evicts a file without a confirmed Walrus copy.

cold → hot (rehydration)

When a cold file is requested, Tusky fetches it back from Walrus to the hot cache. Trigger this via the rehydrate endpoint or the SDK.

any → error

If sync fails after retries, the file status is set to error. The file remains in the hot cache and can be retried.

Tracking status changes

Use webhooks to get notified when files change status:

• file.hot — file confirmed and in hot cache
• file.synced — file synced to Walrus
• file.cold — file evicted from hot cache
• file.error — processing failed

Or poll the file status with the SDK:

const status = await tusky.files.waitForStatus(file.id, ['synced'], {
  timeout: 120000,
});