walrus-quilts

Walrus Quilts

情報源の制約： このスキルのすべての情報は、 Walrus quilt CLI のドキュメントおよび quilt HTTP API のドキュメントに基づいています。 このスキルを拡張する場合は、これらの情報源のみを参照してください。

quilt は複数の blob を 1 つの Walrus ストレージ単位にまとめるため、多数の小さなファイルを保存する際のオーバーヘッドとコストを大幅に削減できます。quilt 内の個々の blob は、標準の BlobId ではなく、QuiltPatchId または識別子を使って取得します。

このスキルのすべてのパターンは、以下の情報源に基づいています。

• https://docs.wal.app/docs/walrus-client/quilts
• https://docs.wal.app/docs/http-api/quilt-http-apis

quilt の操作について不明な点がある場合は、回答する前に該当するページを取得してください。

---

関連スキル

トピック	スキル	読み込むタイミング
CLI の基本	walrus-cli	CLI の一般的なインストール、設定、単一 blob の操作
HTTP API の基本	walrus-http-api	単一 blob の HTTP による保存／読み取り
blob のライフサイクル	walrus-blob-lifecycle	延長、削除、共有（quilt 全体に適用されます）

---

スキルの内容

主な概念

• Quilt。 複数の blob を含む 1 つの Walrus ストレージ単位です。オンチェーンでは、quilt は 1 つの Blob Sui オブジェクトとして表されます。ストレージコストは blob ごとではなく quilt 全体のサイズに基づくため、多数の小さなファイルではオーバーヘッドを節約できます。

• QuiltPatchId。 quilt 内の各 blob に固有の ID です。quilt の内容から導出されるため、異なる内容で quilt を作り直すと、blob の QuiltPatchId は変わります。標準の BlobId とは異なります。

• 識別子。 quilt 内の blob に付ける、人が読める名前（ファイル名など）です。識別子は quilt 内で一意である必要があり、_ で始めることはできません。フィールド名 _metadata は Walrus ネイティブのメタデータ用に予約されています。

• ライフサイクルは quilt 全体に適用されます。 quilt 内の個々の blob を削除、延長、共有することはできません。delete、extend、share などの操作は quilt 全体に適用されます。

選択ガイド

すべての行が quilt を指す場合に限り、quilt を選択してください。いずれかの行が通常の blob を指す場合は、その項目を通常の blob として保存してください。

次元	Quilt を使う場合	通常の blob を使う場合
ファイル数	まとめて保存できる多数の項目がある（数十から数百個、QuiltV1 では最大 666 個）	1 個の項目、または同時に届くことのない項目
個々のサイズ	各項目が小さい（通常は 10 MiB 未満）	1 つの項目がパッチごとの上限約 4 GiB に近い、またはオーバーヘッドが無視できるほど大きい
ライフサイクル	項目のライフタイムが共通している（まとめて保存、延長、廃止する）	項目ごとに削除、延長、共有のスケジュールが必要
アドレス指定	識別子またはタグによる検索で問題ない	内容から導出される BlobId が必要。QuiltPatchId は quilt 全体に依存します
取得	個々の項目をときどき読み取る	すべての項目が頻繁に使われ、個別にキャッシュされる

ドキュメントで指摘されている注意点：ファイルが 1 つだけの quilt ではコスト上の利点がないまま QuiltPatchId による間接参照が加わります。ライフタイムの異なる項目をまとめると、最も長く保持する項目に合わせて quilt 全体を維持する必要があります。また、内容のハッシュで項目を検索するアプリケーションでは、通常の blob を使うか、独自に識別子から内容へのマッピングを用意する必要があります。

TypeScript SDK

client.walrus.writeFiles({ files, epochs, deletable, signer }) は、1 回の呼び出しで指定されたすべてのファイルを 1 つの quilt として保存します。getFiles({ ids }) / getBlob({ blobId }).files({ identifiers | tags | ids }) は、識別子、タグ、または quilt ID を使ってパッチを読み戻します。walrus-ts-sdk を参照してください。

CLI：quilt の保存### CLI：quilt の保存

--paths でディレクトリから保存する

# Store all files from a directory recursively
walrus store-quilt --epochs 5 --paths ./my-assets/

# Store from multiple directories
walrus store-quilt --epochs 10 --paths ./images/ ./documents/ ./data.json

ファイル名が識別子になります。すべての識別子は quilt 内で一意である必要があります。glob パターンを使用できます。

--blobs でカスタム識別子とタグを指定して保存する

walrus store-quilt \
  --blobs '{"path":"photo.jpg","identifier":"walrus","tags":{"color":"grey","size":"medium"}}' \
         '{"path":"icon.png","identifier":"seal","tags":{"color":"grey","size":"small"}}' \
  --epochs 5

identifier が省略されるか null の場合は、ファイル名が使用されます。

有効期間のオプション

通常の walrus store と同じです：--epochs、--earliest-expiry-time、または --end-epoch を指定します。

CLI：クイルから読み取る

識別子で読み取る

walrus read-quilt --out ./downloads/ \
  --quilt-id <QUILT_BLOB_ID> --identifiers walrus.jpg another-walrus.jpg

タグで読み取る

# Download all blobs tagged with species=cat
walrus read-quilt --out ./downloads/ \
  --quilt-id <QUILT_BLOB_ID> --tag species cat

QuiltPatchId で読み取る

walrus read-quilt --out ./downloads/ \
  --quilt-patch-ids <PATCH_ID_1> <PATCH_ID_2>

クイル内のすべてのパッチを一覧表示する

walrus list-patches-in-quilt <QUILT_BLOB_ID>

識別子と QuiltPatchId 値を含むすべてのパッチを返します。

HTTP API：クイルを保存する

パブリッシャーにマルチパートフォームでアップロードして、クイルを保存します：

# Store 2 files with custom identifiers
curl -X PUT "$PUBLISHER/v1/quilts?epochs=5" \
  -F "[email protected]" \
  -F "[email protected]"

フォームのフィールド名が識別子になります。通常のすべての blob クエリパラメーター（epochs、permanent、deletable、send_object_to）もクイルで使用できます。

Walrus ネイティブのメタデータタグを使用して保存する

curl -X PUT "$PUBLISHER/v1/quilts?epochs=5" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F '_metadata=[
    {"identifier": "quilt-manual", "tags": {"creator": "walrus", "version": "1.0"}},
    {"identifier": "logo-2025", "tags": {"type": "logo", "format": "png"}}
  ]'

保存時のレスポンス

レスポンスにはクイルの blobId と、quiltPatchId 値を持つ個々の storedQuiltBlobs が含まれます：

{
  "blobStoreResult": {
    "newlyCreated": {
      "blobObject": {
        "id": "0xe6ac...bc02",
        "blobId": "6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKo",
        "size": 1782224,
        "storage": { "startEpoch": 103, "endEpoch": 104, "storageSize": 72040000 },
        "deletable": false
      },
      "cost": 12075000
    }
  },
  "storedQuiltBlobs": [
    { "identifier": "another_walrus.jpg", "quiltPatchId": "6XUOE-...BAQD..." },
    { "identifier": "walrus.jpg", "quiltPatchId": "6XUOE-...B0AB..." }
  ]
}

HTTP API：クイルから読み取る

# Read by QuiltPatchId
curl "$AGGREGATOR/v1/blobs/by-quilt-patch-id/<PATCH_ID>"

# Read by quilt ID + identifier
curl "$AGGREGATOR/v1/blobs/by-quilt-id/<QUILT_BLOB_ID>/walrus.jpg"

現在、1 リクエストにつき 1 つの blob のみサポートされています。1 回のリクエストでクイルから一括取得する機能は、まだ利用できません。

レスポンスヘッダー

どちらの方法でも、blob の生バイト列が返されます。メタデータは HTTP ヘッダーとして返されます：

• X-Quilt-Patch-Identifier：クイル内における blob の識別子
• ETag：キャッシュ用のパッチ ID またはクイル ID

クイルと個別の blob の使い分け

シナリオ	推奨事項
小さなファイルが多数ある場合（各ファイルが <10 MB）	クイル。 個別の blob には、それぞれ約 64 MB のメタデータオーバーヘッドがかかります。クイルでは、このオーバーヘッドをすべてのファイルに分散できます。
小さな JSON ドキュメントが大量にある場合	クイル。 小さな blob を個別に保存すると、コスト効率が非常に悪くなります。
大きなファイルが 1 つある場合（>10 MB）	個別の blob。 ファイルが 1 つだけなら、クイルにするメリットはありません。
個別にライフサイクルを管理する必要があるファイル	個別の blob。 クイル内の個々のファイルを削除または延長することはできません。
静的ウェブサイトのアセット	クイル。 Walrus Sites が内部でクイルを使用しているのも、このためです。

blob ごとにメタデータオーバーヘッドがかかるため、1 KB の JSON blob を個別に保存するコストは、64 MB のファイルを保存する場合とほぼ同じです。クイルではすべてのデータを 1 つのストレージ単位にまとめることで、この問題を解消できます。

ルール

1. 識別子はクイル内で一意である必要があります。 識別子が重複すると、保存操作は失敗します。
2. 識別子を _ で始めることはできません。 _metadata フィールド名は Walrus ネイティブのメタデータ用に予約されています。
3. ライフサイクル操作はクイル全体に適用されます。 クイル内の個々の blob を削除、延長、または共有することはできません。
4. QuiltPatchId は BlobId ではありません。 blob の QuiltPatchId は、その blob が属するクイルに固有です。同じファイルの内容でも、別のクイルに含まれる場合は異なる QuiltPatchId になります。
5. 小さなファイルが多数ある場合はクイルを使用します。 クイルは blob ごとのオーバーヘッドを削減します。大きなファイルが 1 つだけの場合は、通常の walrus store を使用します。
6. コンテンツアドレス指定は引き続き適用されます。 同じクイルの内容からは、常に同じクイル blob ID が生成されます。

よくある間違い

• クイルから単一の blob を削除しようとする。 クイル全体を削除する必要があります。個々の blob は削除できません。
• クイルから読み取る際に BlobId を使用する。 クイル内の blob は、標準の BlobId ではなく QuiltPatchId または identifier で識別されます。
• ディレクトリ間でファイル名が重複する。 --paths を複数のディレクトリに使用したとき、同じ名前のファイルが 2 つあると識別子が衝突し、保存に失敗します。
• HTTP で一括読み取りできると期待する。 現在、クイルの読み取りでサポートされるのは、HTTP リクエスト 1 回につき 1 つの blob のみです。
• 小さな blob をクイルにせず個別に保存する。 これは最もよくあるコスト上の間違いです。個別の blob には、それぞれ約 64 MB のメタデータオーバーヘッドがかかります。小さな JSON ファイルを 100 個個別に保存すると、まとめてクイルに保存する場合と比べて、およそ 100 倍のコストがかかります。