Skip to main content

Storing Blobs

No public Mainnet publisher

Walrus has no public unauthenticated publisher on Mainnet. There are no plans to create one. On Mainnet, run your own authenticated publisher (or use the Upload Relay or TypeScript SDK directly). The public publisher endpoints below are for Testnet, where WAL has no monetary value.

You can store data using HTTP PUT requests. The following examples use curl to store blobs through a publisher. Set $PUBLISHER to a publisher endpoint from the Network Reference:

# Store the string `some string` for 1 storage epoch
$ curl -X PUT "$PUBLISHER/v1/blobs" -d "some string"
# Store file `some/file` for 1 storage epoch
$ curl -X PUT "$PUBLISHER/v1/blobs" --upload-file "some/file"
Reading a blob right after upload?

When you read through a CDN-fronted aggregator immediately after certification, the CDN might briefly cache a 404 from before the blob propagated. If your app knows the blob was just certified, retry with backoff. See Reading Blobs Right After Upload.

How to configure storage options​

Control how the new blob is created through a combination of query parameters as documented in the OpenAPI specification.

Storage duration​

Specify the lifetime of the blob through the epochs parameter. If you omit the parameter, blobs are stored for 1 epoch.

# Store file `some/file` for 5 storage epochs
$ curl -X PUT "$PUBLISHER/v1/blobs?epochs=5" --upload-file "some/file"

Deletable and permanent blobs​

Starting in v1.33, the publisher creates a deletable blob when you pass no query parameter. To store a permanent blob, which was the default before v1.33, pass permanent=true. The deletable parameter is deprecated and has no effect, so you do not need to set it. Deletable blobs can be removed from Walrus before their expiration time. Permanent blobs cannot, which helps when you need strong availability guarantees:

# Store file `some/file` as a deletable blob:
$ curl -X PUT "$PUBLISHER/v1/blobs" --upload-file "some/file"
# Store file `some/file` as a permanent blob:
$ curl -X PUT "$PUBLISHER/v1/blobs?permanent=true" --upload-file "some/file"
caution

Passing both deletable=true and permanent=true returns an INVALID_BLOB_PERSISTENCE error.

Sending the blob object to another address​

Specify an address to which the resulting Blob object is sent using the send_object_to parameter:

# Store file `some/file` and send the blob object to `$ADDRESS`:
$ curl -X PUT "$PUBLISHER/v1/blobs?send_object_to=$ADDRESS" --upload-file "some/file"

What does a store request return?​

The store HTTP API endpoints return information about stored blobs in JSON format.

Newly created blobs​

When a blob is stored for the first time, the response contains a newlyCreated field with information about it:

$ curl -X PUT "$PUBLISHER/v1/blobs" -d "some other string"

If successful, the response includes the content stored in the blob's corresponding Sui object:

{
  "newlyCreated": {
    "blobObject": {
      "id": "0xe91eee8c5b6f35b9a250cfc29e30f0d9e5463a21fd8d1ddb0fc22d44db4eac50",
      "registeredEpoch": 34,
      "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
      "size": 17,
      "encodingType": "RS2",
      "certifiedEpoch": 34,
      "storage": {
        "id": "0x4748cd83217b5ce7aa77e7f1ad6fc5f7f694e26a157381b9391ac65c47815faf",
        "startEpoch": 34,
        "endEpoch": 35,
        "storageSize": 66034000
      },
      "deletable": true
    },
    "resourceOperation": {
      "registerFromScratch": {
        "encodedLength": 66034000,
        "epochsAhead": 1
      }
    },
    "cost": 132300
  }
}

Already certified blobs​

When the publisher finds a certified blob with the same blob ID and a sufficient validity period, it returns an alreadyCertified structure:

{
  "alreadyCertified": {
    "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
    "event": {
      "txDigest": "4XQHFa9S324wTzYHF3vsBSwpUZuLpmwTHYMFv9nsttSs",
      "eventSeq": "0"
    },
    "endEpoch": 35
  }
}

The event field returns the Sui event ID that you can use to find the object creation transaction through Suiscan or a Sui SDK.