Bucket

`recall bucket`

The bucket subcommand (aliased as bu) has the following subcommands:

create: Create a new bucket contract.
list: List buckets by owner in a subnet.
add: Add an object into the bucket.
get: Get an object from the bucket.
delete: Delete an object from the bucket.
query: Query objects in the bucket.
metadata: Set new metadata for an object.

When you create objects, the key is a custom identifier that, by default, uses the / delimiter to create a key-based hierarchy. The value is the data you want to store, which can be a file path. A best practice is to decide on a key naming convention that makes sense for your data, such as <namespace>/<id> or similar. The hierarchical structure of the key allows for easy retrieval of data by prefixes, which is explained below (see the query subcommand).

Create

Create a new Bucket contract.

recall bucket create

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--alias`	No	Alias for the bucket (shorthand for `--metadata "alias=value"`).
`-m, --metadata`	No	User-defined metadata.
`--gas-limit`	No	Gas limit for the transaction.
`--gas-fee-cap`	No	Maximum gas fee for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--gas-premium`	No	Gas premium for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--sequence`	No	Sequence (i.e., nonce) for the transaction.

Example:

Create a new bucket contract.

recall bucket create

{
  "address": "0xff0000000000000000000000000000000000008f",
  "tx": {
    "transactionHash": "0xab575c9ac1c175b4c5ebd2951c6819a960f4ac917083960ae1320b3f042c5aed",
    "transactionIndex": "0x0",
    "blockHash": "0x8ad132d45814732626fb1537bc6c9bbb51e930b22b209807f05315a5425240a2",
    "blockNumber": "0x3ef0",
    "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
    "to": "0xff00000000000000000000000000000000000011",
    "cumulativeGasUsed": "0x134fb57",
    "gasUsed": "0x134fb57",
    "contractAddress": null,
    "logs": [],
    "status": "0x1",
    "root": "0x22aef53ff99dde1ddd59e244cd4dd6531833e41045f3a98ee0d69e52f143b18d",
    "logsBloom": "0x00...",
    "type": "0x2",
    "effectiveGasPrice": "0x8"
  }
}

Create a new bucket with an alias.

recall bucket create --alias foo

Or create a new bucket with arbitrary metadata.

recall bucket create --metadata "bar=baz"

List buckets

List buckets by owner in a subnet.

recall bucket list {--private-key <PRIVATE_KEY> | --address <ADDRESS>}

You must pass either the --private-key or --address flag. An address must be in the delegated t410 or 0x format.

recall bucket list --private-key <PRIVATE_KEY>: Query with a private key (or read from your .env file).
recall bucket list --address <ADDRESS>: Query a t410 or 0x address.

Flag	Required?	Description
`-p, --private-key`	Yes, if no `address`	Wallet private key (ECDSA, secp256k1) for signing transactions.
`-a, --address`	Yes, if no `private-key`	Account address; the signer's address is used if no address is given.
`--height`	No	Query at a specific block height (default: `committed`).

Examples:

Query data contracts by a hex address:

recall bucket list --address 0x90f79bf6eb2c4f870365e785982e1f101e93b906

[
  {
    "address": "0xff0000000000000000000000000000000000008f",
    "kind": "Bucket",
    "metadata": {
      "alias": "foo"
    }
  }
]

Or at a specific block height:

recall bucket list --height 1234

Add an object

Add an object with a key prefix.

recall bucket add \
--address <ADDRESS> \
--key <KEY> \
<FILE_PATH>

Positionals	Description
`<FILE_PATH>`	File path to upload.

You must set the bucket address and object key. The metadata, ttl, and overwrite flags are optional but useful in various scenarios.

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`-a, --address`	Yes	Bucket contract address.
`-k, --key`	Yes	Key of the object to upload.
`-m, --metadata`	No	User-defined metadata.
`--ttl`	No	Object time-to-live (TTL) duration.
`-o, --overwrite`	No	Overwrite the object if it already exists.
`-b, --broadcast-mode`	No	Broadcast mode for the transaction: `commit`, `sync`, or `async` (default: `commit`).
`--gas-limit`	No	Gas limit for the transaction.
`--gas-fee-cap`	No	Maximum gas fee for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--gas-premium`	No	Gas premium for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--sequence`	No	Sequence (i.e., nonce) for the transaction.

Examples:

Push a file to the bucket—and note the path must be absolute. We can create a file with the following contents:

echo '{"hello":"world"}' > ~/hello.json

Add the file to the bucket:

recall bucket add \
--address 0xff0000000000000000000000000000000000008f \
--key "hello/world" \
~/hello.json

{
  "transactionHash": "0x5acbd332ec7ac29a4e70cff6998bad70cadb2fb3f757a210f2b4486a02855f36",
  "transactionIndex": "0x0",
  "blockHash": "0x2aae63f404dba64edf9ac765407a1b16a848db05b8a4a4d55d764e8226733628",
  "blockNumber": "0x4718",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff0000000000000000000000000000000000008f",
  "cumulativeGasUsed": "0x2c16130",
  "gasUsed": "0x2c16130",
  "contractAddress": null,
  "logs": [
    {
      "address": "0xff000000000000000000000000000000000000a9",
      "topics": [
        "0x3b19e204348bcf64c18e18a0ad19e5871fa8e1ed43d1c9e88bd33898538d662d",
        "0x8e4c7c1b99dbfd50e7a95185fead5ee1448fa904a2fdd778eaf5f2dbfd629a99",
        "0x0000000000000000000000000000000000000000000000000000000000000006",
        "0x0000000000000000000000000000000000000000000000000000000000019898"
      ],
      "data": "0x",
      "blockHash": "0x2aae63f404dba64edf9ac765407a1b16a848db05b8a4a4d55d764e8226733628",
      "blockNumber": "0x4718",
      "transactionHash": "0x5acbd332ec7ac29a4e70cff6998bad70cadb2fb3f757a210f2b4486a02855f36",
      "transactionIndex": "0x0",
      "logIndex": "0x0",
      "transactionLogIndex": "0x0",
      "removed": false
    }
  ],
  "status": "0x1",
  "root": "0x789b3619d2729d15d5b6158b7628923ff7846483452288c13e509d455e78989c",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Include metadata in the object along with ttl and overwrite:

recall bucket add \
--address 0xff0000000000000000000000000000000000008f \
--key "hello/world" \
--metadata "alias=foo" \
--ttl 3600 \
--overwrite \
~/hello.json

Get an object

Get an object from the bucket contract.

recall bucket get --address <ADDRESS> <KEY>

Positionals	Description
`<KEY>`	Key of the object to get.

Note that when you retrieve the object, it will be written to stdout.

Flag	Required?	Description
`-a, --address`	Yes	Bucket contract address.
`--object-api-url`	No	Node Object API URL.
`--range`	No	Range of bytes to get from the object (format: `"start-end"`; inclusive). Example: "0-99" => first 100 bytes.
`--height`	No	Query at a specific block height (default: `committed`).

Examples:

Get an object and write to stdout (default behavior):

recall bucket get \
--address 0xff0000000000000000000000000000000000008f \
"hello/world"

{ "hello": "world" }

Download the output to a file by piping the output:

recall bucket get \
--address 0xff0000000000000000000000000000000000008f \
"hello/world" > downloaded.json

Or make a range request for a subset of bytes:

recall bucket get \
--address 0xff0000000000000000000000000000000000008f \
--range "10-14" \
"hello/world"

world

Delete an object

Delete an object from the bucket.

recall bucket delete \
--address <ADDRESS> \
<KEY>

Positionals	Description
`<KEY>`	Key of the object to get.

Similar to when you add an object, you can specify gas settings or alter the broadcast mode.

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`-a, --address`	Yes	Bucket contract address.
`--object-api-url`	No	Node Object API URL.
`-b, --broadcast-mode`	No	Broadcast mode for the transaction: `commit`, `sync`, or `async` (default: `commit`).
`--gas-limit`	No	Gas limit for the transaction.
`--gas-fee-cap`	No	Maximum gas fee for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--gas-premium`	No	Gas premium for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--sequence`	No	Sequence (i.e., nonce) for the transaction.

Example:

Delete an existing object:

recall bucket delete \
--address 0xff0000000000000000000000000000000000008f \
"hello/world"

{
  "transactionHash": "0xace2770f8bdb120be1849fa472a1449ecf970bc8a95e140f142860c79dd2be9c",
  "transactionIndex": "0x0",
  "blockHash": "0x844603ae5d938fa204b83ba61b3a885ca7cbdc16795e1ee577b4e9d07159085a",
  "blockNumber": "0x478b",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff000000000000000000000000000000000000a9",
  "cumulativeGasUsed": "0x259ae1f",
  "gasUsed": "0x259ae1f",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0x6b142f271f11d935999cd978283bdc91733543d82a29136466ab9df56d73bc70",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Query objects

Query across all objects in the bucket.

recall bucket query --address <ADDRESS>

Performing a query lists all keys that match a given prefix up to and including the delimiter. If the key supplies a delimiter, then the results stop there—essentially, listing subfolders, but none lower. Think of it as you would when listing files in a directory. If you list the contents of a folder, you'll see all subfolders, but you won't see the contents of one of those subfolders.

For example, if you have the keys hello/world, hello/data, and hello/world/child, and you query for the prefix hello/, you will get the objects at hello/world and hello/data but not hello/world/child since its "nested" under the prefix hello/world/ (note: inclusive of the / at the end).

Flag	Required?	Description
`-a, --address`	Yes	Bucket contract address.
`-p, --prefix`	No	The prefix to filter objects by (defaults to empty string).
`-d, --delimiter`	No	The delimiter used to define object hierarchy (default: `/`).
`-o, --offset`	No	The offset from which to start listing objects (default: `0`)
`-l, --limit`	No	The maximum number of objects to list, where `0` indicates max (10k)(default: `0`)
`--height`	No	Query at a specific block height (default: `committed`).

Examples:

Get all objects but without any filtering. Since the object keys have a delimiter included, you'll see the common prefix hello/, but no objects are listed since the "root" is the prefix:

recall bucket query \
--address 0xff0000000000000000000000000000000000008f

{
  "objects": [],
  "common_prefixes": ["hello/"],
  "next_key": null
}

Get all objects under a specific prefix. In this case, the response will include all objects under the hello/ prefix, and since there are no "child" objects that match hello/ (e.g., hello/world/child), the common_prefixes array will be empty, so you know there are no more sub-objects to list:

recall bucket query \
--address 0xff0000000000000000000000000000000000008f \
--prefix "hello/"

{
  "objects": [
    {
      "key": "hello/world",
      "value": {
        "hash": "rzghyg4z3p6vbz5jkgc75lk64fci7kieul65o6hk6xznx7lctkmq",
        "size": 6,
        "metadata": {
          "content-type": "application/octet-stream"
        }
      }
    }
  ],
  "common_prefixes": [],
  "next_key": null
}

Get objects and filter by a prefix from a starting key and a limit. In the example above, lets say a "hello/data" object was created after "hello/world". When we query the bucket, it will be the first object listed since we're offsetting and starting from the "hello/data" object. We'll also include the rest of the optional flags for demonstration purposes:

recall bucket query \
--address 0xff0000000000000000000000000000000000008f \
--prefix hello/ \
--start-key hello/data \
--limit 1 \
--delimiter "/"

{
  "objects": [
    {
      "key": "hello/data",
      "value": {
        "hash": "rzghyg4z3p6vbz5jkgc75lk64fci7kieul65o6hk6xznx7lctkmq",
        "size": 6,
        "metadata": {
          "content-type": "application/octet-stream"
        }
      }
    }
  ],
  "common_prefixes": [],
  "next_key": null
}

Add metadata to an object

Add metadata to an existing object.

recall bucket metadata --address <ADDRESS> --key <KEY> --metadata <METADATA>

Flag	Required?	Description
`-a, --address`	Yes	Bucket contract address.
`-k, --key`	Yes	Key of the object to add metadata to.
`-m, --metadata`	Yes	Metadata to add to the object.

Example:

Add metadata to an existing object:

recall bucket metadata \
--address 0xff0000000000000000000000000000000000008f \
--key "hello/world" \
--metadata "alias=foo"

{
  "transactionHash": "0x37aa795888d7b642e8658ef9d61ad44147d6a092e943dcf2e63403cd293d82da",
  "transactionIndex": "0x0",
  "blockHash": "0xe317aec6fa81c6b1153df8bcb5ed9e951bb31033e1bdebf9099e97ef5adcc637",
  "blockNumber": "0x49fb",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff0000000000000000000000000000000000008f",
  "cumulativeGasUsed": "0x930d36",
  "gasUsed": "0x930d36",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0x9bba4f579a536465102c50bbb9c3c25dae4effe11f2b9d314757704c3dbef984",
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Bucket

On this page