walrus-http-api

Walrus HTTP API

ソースの制約： このスキルの情報はすべて、 Walrus HTTP API ドキュメントを参照しています。 このスキルを拡張するときは、これらのソースのみを使用してください。

Walrus は、パブリッシャー（書き込み）サービスとアグリゲーター（読み取り）サービスを通じて REST API を提供します。これは、あらゆる言語で利用できる最もシンプルな統合方法です。HTTP PUT で BLOB を保存し、HTTP GET で読み取ります。SDK のインストールは不要です。

このスキルのパターンは、すべて次のドキュメントに基づいています。

• https://docs.wal.app/docs/http-api/storing-blobs
• https://docs.wal.app/docs/http-api/reading-blobs

エンドポイントについて不明な点がある場合は、回答する前に該当するページを取得してください。

---

関連スキル

トピック	スキル	読み込むタイミング
Quilt の HTTP エンドポイント	walrus-quilts	HTTP 経由でバッチ化された BLOB を保存／読み取るとき
CLI	walrus-cli	HTTP の代わりに walrus バイナリを使用するとき
TypeScript SDK	walrus-ts-sdk	公式 TS SDK を使用するとき
BLOB 管理	walrus-blob-lifecycle	BLOB の有効期限を延長、削除、共有するとき
暗号化	walrus-data-security	保存前に暗号化するとき

---

スキルの内容

主な概念

• パブリッシャー。 BLOB データを受け取り、エンコード、スライバーの配布、オンチェーン登録を処理する HTTP サービスです。パブリッシャーに PUT してデータを保存します。Mainnet には、認証なしで利用できる公開パブリッシャーはありません。Mainnet では、独自の認証済みパブリッシャーを実行するか、アップロードリレーを使用するか、TypeScript SDK を直接使用してください。公開パブリッシャーのエンドポイントがあるのは Testnet のみです。

• アグリゲーター。 Walrus のストレージノードから BLOB を読み取り、GET リクエストで返す HTTP サービスです。アグリゲーターは読み取り専用で、CDN の背後に配置できます。

• BLOB ID とオブジェクト ID。 BLOB ID はコンテンツを識別します。Sui オブジェクト ID は、オンチェーンの Blob オブジェクトを識別します。どちらを使っても読み取れます。オブジェクト ID による読み取りでは、HTTP ヘッダー属性もサポートされます。

• 整合性チェック。 アグリゲーターは読み取り時に BLOB の整合性を検証します。?strict_consistency_check=true を指定すると厳密なチェックを有効にできます。書き込み元が既知で信頼できる場合は、?skip_consistency_check=true を指定してチェックを省略できます。

BLOB の保存（パブリッシャー）

HTTP PUT を使用してパブリッシャーにデータを保存します。

# Store a string for 1 epoch (default)
curl -X PUT "$PUBLISHER/v1/blobs" -d "some string"

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

クエリパラメーター

パラメーター	効果	デフォルト
epochs	ストレージのエポック数	1
deletable=true	有効期限前に所有者が BLOB を削除できます	新しい BLOB のデフォルト
permanent=true	有効期限前に BLOB を削除できません	明示的な指定が必要
send_object_to	生成された Blob Sui オブジェクトを別のアドレスに送信します（スポンサー付きアップロードで、ウォレットを持たないユーザーに所有権を渡す方法）	パブリッシャーのウォレット
reuse_resources=true	パブリッシャーのウォレットがすでに所有しているストレージオブジェクトまたは BLOB オブジェクトを再利用し、新たに登録することを避けます	false。複数の保存処理で同じウォレットを同時に使用する場合はオフにしてください

# Store as permanent for 5 epochs
curl -X PUT "$PUBLISHER/v1/blobs?epochs=5&permanent=true" --upload-file "file.dat"

# Store and send the blob object to another address
curl -X PUT "$PUBLISHER/v1/blobs?send_object_to=$ADDRESS" --upload-file "file.dat"

保存レスポンス：新規作成

BLOB が初めて保存される場合：

{
  "newlyCreated": {
    "blobObject": {
      "id": "0xe91e...c50",
      "registeredEpoch": 34,
      "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
      "size": 17,
      "encodingType": "RS2",
      "certifiedEpoch": 34,
      "storage": {
        "id": "0x4748...5faf",
        "startEpoch": 34,
        "endEpoch": 35,
        "storageSize": 66034000
      },
      "deletable": false
    },
    "resourceOperation": {
      "registerFromScratch": {
        "encodedLength": 66034000,
        "epochsAhead": 1
      }
    },
    "cost": 132300
  }
}

保存レスポンス：認証済み

同一のコンテンツが、十分な有効期間を保ってすでに存在する場合：

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

event フィールドには、Suiscan でトランザクションを検索する際に使用できる Sui イベント ID が含まれています。

BLOB の読み取り（アグリゲーター）

HTTP GET を使用してアグリゲーターから BLOB を読み取ります。

# Read by blob ID
curl "$AGGREGATOR/v1/blobs/<BLOB_ID>" -o output.file

# Read by Sui object ID (also returns HTTP header attributes)
curl "$AGGREGATOR/v1/blobs/by-object-id/<OBJECT_ID>" -o output.file

オブジェクト ID による読み取りでは、次の属性キーが認識され、HTTP ヘッダーとして返されます：content-disposition、content-encoding、content-language、content-location、content-type、link。

パブリッシャー、アグリゲーター、アップロードリレー：どれを使うべきか

サービス	方向	メインネットでの利用可否	ウォレットが必要
パブリッシャー	書き込み（PUT）	公開パブリッシャーはありません。独自に実行するか、アップロードリレー／SDKを使用してください。	はい（WAL + SUI）
アップロードリレー	書き込み（PUT）	https://upload-relay.mainnet.walrus.space	はい（WAL + SUI + 任意のチップ）
アグリゲーター	読み取り（GET）	多数の公開アグリゲーターがあり、手数料はかからず、ウォレットも不要です。	いいえ

• メインネットアグリゲーター（Mysten Labs）： https://aggregator.walrus-mainnet.walrus.space
• テストネットアグリゲーター（Mysten Labs）： https://aggregator.walrus-testnet.walrus.space
• テストネットパブリッシャー（Mysten Labs）： https://publisher.walrus-testnet.walrus.space

公開アグリゲーターの全リストは、docs.wal.app/operators.json（JSON）および公開サービスのページで確認できます。公開アグリゲーターはCORSヘッダーを設定しているため、ブラウザーから直接読み取れます。

スポンサー付きアップロードとウォレット不要のアップロード

ほとんどのユーザーはSUIもWALも保有していません。Walrusにはガス代をスポンサーする組み込み機能がありません。スポンサーするには、自分のウォレットのいずれかを使ってストア処理を実行し、費用を支払う必要があります。方法は3つあります。

方法	署名者	支払者	ユーザーにウォレットは不要か	最適な用途
バックエンドパブリッシャー	パブリッシャーのウォレット	アプリ	はい	HTTP経由で生のバイト列を受け付け、ストレージ費用を負担するバックエンド
アップロードリレー	クライアントまたはアプリの署名者	クライアントまたはアプリの署名者。設定されている場合はリレーへのチップも必要	アプリが署名を管理する場合のみ	多数のノード接続を開けないブラウザーおよびモバイルのクライアント
直接SDKを使用	コードで設定した署名者	アプリのウォレット	バックエンドが署名者を保持する場合ははい	Walrusを直接統合し、コード内で署名を管理するバックエンド

参照アーキテクチャ：クライアントは独自の認証情報を使ってバックエンドに認証します。バックエンドはポリシー（クォータ、サイズ、期間）を適用し、バイト列をパブリッシャーに転送します。パブリッシャーは資金を補充したウォレットで保存し、send_object_to=<address> を指定して、Blob オブジェクトをユーザーに送信します。バックエンドはblob IDを返します。すべてのストア処理では、実際にWALとSUIが消費されます（1つ目のトランザクションでリザーブと登録を行い、2つ目で認証します）。無料プランはありません。

ドキュメントに記載されている運用上の注意点：

• メインネットで、認証のないパブリッシャーを公開しないでください。 アクセスできる人なら誰でも、あなたのウォレットのSUIとWALを消費できます。認証付きパブリッシャーのJWTフロー、または独自のゲートウェイを前段に配置してください。
• 1つのウォレットから多数のストア処理に同時に署名しないでください。 同時実行されるトランザクションは、所有する同じガスオブジェクトやストレージオブジェクトを取り合います。パブリッシャーは内部のサブウォレットを使用します。独自のアップローダーを構築する場合も、この仕組みを再現してください。
• ウォレットを共有する場合は、reuse_resources をオフにしてください。 リソースの再利用を有効にすると、進行中の2つのアップロードが同じオブジェクトを取り合い、blobが登録されても認証されないままになることがあります。
• 資金用ウォレットの残高を十分に保ってください。 メインウォレットのSUIとWALの両方を監視してください。パブリッシャーはそこからサブウォレットに資金を補充します。

バイト範囲とストリーミングメディア

アグリゲーターはHTTPの Range ヘッダーをサポートし、206 Partial Content を返します。これにより、ブラウザーで動画の途中にシークできます。クエリパラメーターを使う方法もあります。

curl -H "Range: bytes=0-999" "$AGGREGATOR/v1/blobs/<BLOB_ID>"
curl "$AGGREGATOR/v1/blobs/<BLOB_ID>/byte-range?start=0&length=1024"

<video> または <audio> 要素では、アグリゲーターのURLを src として使用できます。blob IDによる読み取りではコンテンツタイプが返されず、アグリゲーターは意図的にタイプのスニッフィングをブロックするため、blobに content-type 属性を設定し、オブジェクトID（/v1/blobs/by-object-id/<OBJECT_ID>）で読み取ってください。そうするとヘッダーが返され、ブラウザーはダウンロードせずに再生します。バイト範囲の読み取りでは、取得したバイト列のみが検証され、blob全体は検証されません。

システム情報の照会### システム情報の照会

# Get current epoch, storage cost, and network parameters
curl "$AGGREGATOR/v1/info"

エポック番号、エポック期間、システムパラメーターを返します。コストの計算や、ストアリクエストで epochs を設定する前に現在のエポックを確認する際に便利です。

ルール

1. Mainnet に公開パブリッシャーはありません。 Mainnet では、認証済みのパブリッシャーを自分で実行するか、TypeScript SDK／アップロードリレーを使用してください。公開エンドポイントは Testnet 専用です。
2. 新しい blob はデフォルトで削除可能です。 可用性を保証する必要がある場合は、明示的に permanent=true を設定してください。
3. アップロード直後の読み取りは再試行してください。 CDN の背後にあるアグリゲーターは、blob が伝播する前の 404 を一時的にキャッシュする場合があります。バックオフを設けて再試行してください。
4. コンテンツの読み取りには blob ID、属性付きの読み取りには object ID を使用してください。 object ID で読み取ると、blob の属性に基づくカスタム HTTP ヘッダーが返されます。blob ID で読み取った場合は返されません。
5. レスポンスの種類を確認してください。 ストアのレスポンスは newlyCreated または alreadyCertified のいずれかです。どちらも成功を表します。

よくある間違い

• Mainnet に公開パブリッシャーがあると思い込む。 公開パブリッシャーはありません。自分で実行するか、アップロードリレーを使用するか、TypeScript SDK を直接使用する必要があります。Mainnet の書き込みには、https://upload-relay.mainnet.walrus.space のアップロードリレーが最も簡単です。
• レスポンスで alreadyCertified を確認しない。 同一のコンテンツに十分な有効期間がすでにある場合、パブリッシャーはこの値を返します。これはエラーではありません。
• 保存直後に読み取って 404 が返される。 CDN のキャッシュにより、一時的に 404 が発生する場合があります。バックオフを設けて再試行してください。
• epochs を省略して、1 エポック分のストレージになる。 デフォルトは 1 エポックです。必ず epochs を明示的に設定してください。
• パブリッシャーとアグリゲーターの役割を混同する。 パブリッシャーは保存（PUT）し、アグリゲーターは読み取り（GET）を行います。これらは URL が異なる別々のサービスです。
• 503 BLOB_UNAVAILABLE を恒久的なエラーとして扱う。 v1.47 以降、blob が一時的に取得できない場合、アグリゲーターは再試行可能な 503（500 ではなく）を返します。バックオフを設けて再試行してください。
• blob ID で読み取ったときにコンテンツタイプが返されると期待する。 content-type などの属性ヘッダーを返すのは、object ID による読み取りのみです。
• パブリッシャーで 413 Payload Too Large が発生する。 一部のパブリッシャーではアップロードサイズに上限があります（たとえば、公開 Testnet パブリッシャーは 10 MiB）。大きなファイルには CLI、TypeScript SDK、または自分で実行するパブリッシャーを使用してください。
• 小さな blob なのに storageSize が約 66 MB になる理由がわからない。 Walrus は blob のサイズにかかわらず、blob ごとに約 64 MB の固定メタデータオーバーヘッドを追加します。約 10 MB 未満の blob では、メタデータのコストが大部分を占めます。小さな blob を多数扱う場合は quilt を使用してください。
• 古いアグリゲーター URL を使用する。 aggregator.walrus.site と aggregator.devnet.walrus.space は古い URL です。Mainnet には aggregator.walrus-mainnet.walrus.space、Testnet には aggregator.walrus-testnet.walrus.space を使用してください。