用途:Quilt 是单个 Walrus 存储单元,内部包含多个 blob。链上表示为单个 Blob Sui 对象,存储费用按 quilt 总大小计算而非按单个 blob,从而为大量小文件节省开销。适合许多小于约 10 MiB 的小文件、大量小 JSON、静态网站资源等共享同一生命周期的场景;单个大文件或需要独立生命周期的文件应使用普通 blob。
主要能力:使用 CLI 的 walrus store-quilt 从目录递归存储,文件名成为标识符,也支持 --blobs 自定义标识符与标签;可用 --epochs、--earliest-expiry-time 或 --end-epoch 控制生命周期。读取可用 walrus read-quilt 按 --identifiers、--tag 或 --quilt-patch-ids 下载,用 walrus list-patches-in-quilt 列出所有 patch。HTTP API 可通过 publisher 的 PUT /v1/quilts 以 multipart 表单存储,表单字段名成为标识符,并支持 _metadata 字段携带 Walrus 原生标签;读取用 /v1/blobs/by-quilt-patch-id/<PATCH_ID> 或 /v1/blobs/by-quilt-id/<QUILT_BLOB_ID>/<identifier>,返回原始字节,元数据在响应头中。TypeScript SDK 用 client.walrus.writeFiles 存储、getFiles/getBlob 读取。
限制与规则:标识符在 quilt 内必须唯一且不能以 _ 开头,_metadata 为保留字段;生命周期操作(删除、延长、共享)作用于整个 quilt,不能单独操作内部 blob;QuiltPatchId 不是 BlobId,取决于整个 quilt 内容;目前 HTTP 读取一次仅支持一个 blob,不支持批量检索。常见错误包括试图删除单个 blob、用 BlobId 读取 quilt 内文件、多目录同名导致标识符冲突,以及把大量小文件逐个存储而不用 quilt。