Lib.rs

› 密码学 › 神奇豆
#upload #arweave #nft #solana #metaplex #command-line-utilities

bin+lib arloader

用于上传文件到 Arweave 的命令行应用程序和库

由 Caleb 及 5 位贡献者 开发

52 个版本

0.1.63 2022年5月12日
0.1.62 2022年3月29日
0.1.59 2022年2月26日
0.1.55 2022年1月30日
0.1.25 2021年11月30日

#2353 in 神奇豆

Download history 3/week @ 2024-04-28 10/week @ 2024-06-02 2/week @ 2024-06-09 1/week @ 2024-06-16 3/week @ 2024-07-07 1187/week @ 2024-07-28

1,190 每月下载量
用于 warp_dre

Apache-2.0

2MB
5.5K SLoC

crates.io build status docs.rs Crates.io

arloader

用于上传文件到 Arweave 的命令行应用程序和客户端。Arweave 可永久存储文档和应用程序。

使用一条命令上传数 GB 的文件。文件异步读取并发布到 arweave.net，同时在多个线程上并行执行计算密集型的捆绑准备。

内容

安装

  1. 使用 arloader 的最简单方法是下载适用于您系统（Linux 或 Mac）的二进制文件（从 github 的发行版）。

如果您已安装带有夜间工具链的 rust，则可以从 crates.io 进行安装。

rustup default nightly
cargo install arloader

  1. 在此 处 获取 Arweave 钱包 json 文件。

  2. 如果您打算使用 AR 支付交易，请 获取 AR 代币。

  3. 如果您打算使用 SOL，请获取一个 Solana 钱包 json 文件并将一些 SOL 转移到其中。

NFT 使用

下面的单个upload-nfts命令假定您为每个NFT都有一对图像和元数据文件。要了解上传文件的每个步骤，请查看upload_nfts_steps。有关上传多个媒体文件的示例，请参阅multiple_asset_files。

要获取如何在Solana中创建NFT的入门级步骤指南（从创建钱包到使用arloader上传资产，再到在市场上列出），请查看这篇medium文章。

创建上传文件夹

将您的资产和相关的元数据文件（扩展名为.json）放在一个单独的文件夹中。您可以使用任何类型的文件。Arloader会自动为上传添加一个内容类型标签，以便浏览器在从Arweave访问时正确处理。

├── 0.json
├── 0.png
├── 1.json
├── 1.png
├── 2.json
├── 2.png
├── 3.json
├── 3.png
├── 4.json
├── 4.png
├── 5.json
├── 5.png

上传资产

如果您想使用SOL为交易提供资金，请运行以下命令，其中<FILE_PATHS>与您的资产文件相匹配。

arloader upload-nfts <FILE_PATHS> --with-sol --sol-keypair-path <SOL_KEYPAIR_PATH> --ar-default-keypair

例如，如果您正在上传mp4文件作为您的资产，并且它们在一个名为path/to/my/assets的文件夹中，并且您的SOL密钥对的路径是path/to/my/solkeypair.json，则输入

arloader upload-nfts path/to/my/assets/*.mp4 --with-sol --sol-keypair-path path/to/my/solkeypair.json --ar-default-keypair

要使用AR为交易提供资金，则运行

arloader upload-nfts <FILE_PATHS> --ar-keypair-path <AR_KEYPAIR_PATH>

这将首先上传您的资产，将状态记录到新创建的名为arloader_<RANDOM_CHARS>的目录中，该目录位于资产所在的文件夹中。

然后将从记录的状态创建一个清单文件并上传。清单是一个特殊文件，Arweave使用它通过名称访问您的文件，相对于清单事务的id：https://arweave.net/<MANIFEST_ID>/<FILE_PATH>。您仍然可以通过其id在https://arweave.net/<BUNDLE_ITEM_ID>访问您的文件，但创建和上传清单使您可以选择使用任一。上传后，清单文件本身可以在https://arweave.net/tx/<MANIFEST_ID>/data.json上在线访问。

更新元数据和上传

接下来，您的元数据文件将使用上传的资产链接进行更新。对于upload-nfts命令，arloader会将元数据中的image键替换为新创建的链接，并将新链接追加到元数据中的files键。默认情况下，它使用id链接，https://arweave.net/<BUNDLE_ITEM_ID>，但如果您希望使用基于文件路径的链接，https://arweave.net/<MANIFEST_ID>/<FILE_PATH>，则可以传递--link-file标志。

在您的元数据文件被更新后，它们将被上传，接着创建和上传您的元数据文件的清单文件。

所有文件上传完成后，您上传的元数据文件的链接，用于链上代币元数据，可以在以下位置找到：arloader_<RAND_CHAR>/metadata/manifest_<TXID>.json。

{
    "0.json": {
        "id": "ScU9mEuKBbPX5o5nv8DZkDnZuJbzf84lyLk-uLVDqNk",
        "files": [
            {
                "uri": "https://arweave.net/ScU9mEuKBbPX5o5nv8DZkDnZuJbzf84lyLk-uLVDqNk",
                "type": "application/json"
            },
            {
                "uri": "https://arweave.net/fo9P3OOq78REajk48vFWbKfIhw6mDzgjANQIh3L7Njs/0.json",
                "type": "application/json"
            }
        ]
    },
    "1.json": {
        "id": "8APeQ5lW0-csTcBaGdPBDLAL2ci2AT9pTn2tppGPU_8",
        "files": [
            {
                "uri": "https://arweave.net/8APeQ5lW0-csTcBaGdPBDLAL2ci2AT9pTn2tppGPU_8",
                "type": "application/json"
            },
            {
                "uri": "https://arweave.net/fo9P3OOq78REajk48vFWbKfIhw6mDzgjANQIh3L7Njs/1.json",
                "type": "application/json"
            }
        ]
    },

如果您使用Metaplex Candy Machine创建NFT，您可以在与<MANIFEST_PATH>相同的目录中使用名为metaplex_items_<MANIFIEST_ID>.json的文件。与更新元数据文件一样，Arloader默认使用基于id的链接，即https://arweave.net/<BUNDLE_ITEM_ID>，但您可以通过传递--link-file标志来使用基于文件的链接，即https://arweave.net/<MANIFEST_ID>/<FILE_PATH>。

{
        "0": {
            "link": "uri link",
            "name": "name",
            "onChain": false
        },
        "1": {
            "link": "uri link",
            "name": "name",
            "onChain": false
        },

确认所有交易

在创建您的代币之前，请确保所有交易至少已确认25次。运行以下命令，其中<LOG_DIR>指您的资产文件夹中自动创建的以arloader_开头的目录。

交易状态为NotFound的主要原因是因为它们被矿工拒绝，因为没有足够的奖励或奖励太大。有关通过传递可选的--reward-multiplier参数增加奖励的说明，请参阅奖励倍数。

arloader update-nft-status <LOG_DIR>

Updating asset bundle statuses...

 bundle txid                                   items      KB  status       confirms
------------------------------------------------------------------------------------
 kmgLCgV-dB-DGML8cvFwuP3a-ZKedz7nyDuEsqYPTis      10     980  Confirmed          60
Updated 1 statuses.


Updating metadata bundle statuses...

 bundle txid                                   items      KB  status       confirms
------------------------------------------------------------------------------------
 kmgLCgV-dB-DGML8cvFwuP3a-ZKedz7nyDuEsqYPTis      10     980  Confirmed          60
Updated 1 statuses.


Updating asset manifest status...

 id                                           status     confirms
------------------------------------------------------------------
 URwQtoqrbYlc5183STNy3ZPwSCRY4o8goaF7MJay3xY  Confirmed        60


Updating metadata manifest status...

 id                                           status     confirms
------------------------------------------------------------------
 fo9P3OOq78REajk48vFWbKfIhw6mDzgjANQIh3L7Njs  Confirmed        57

通用使用

如果您上传多个文件，您几乎总是应该使用捆绑。捆绑将多个文件打包在一起，作为一个单一的交易。这比上传多个单独的文件要好，因为您只需等待一个交易被确认。一旦捆绑交易被确认，您的所有文件都将可用。较大的交易和较大的奖励对矿工更具吸引力，这意味着较大的捆绑交易比多个较小的单个交易更有可能快速写入。

Arloader将创建必要的捆绑次数来上传您的所有文件。您的文件异步读取，并行跨多个线程捆绑，然后发布到arweave.net。Arloader支持的最大捆绑大小为200 MB，默认为100 MB。这对于单个文件大小不超过100 MB应该没有问题。如果您的文件大小超过100 MB（但小于200 MB），您可以使用--bundles-size参数指定更大的捆绑大小 - 例如，使用--bundle-size 200指定200 MB的大小。如果您的文件大小超过200 MB，您可以通过传递--no-bundle标志将它们作为单个文件上传。

估算成本

要估算上传您的文件的成本，请运行

arloader estimate <FILE_PATHS>

<FILE_PATHS>可以是glob，例如path/to/my/files/*.png，或者空格分隔的一个或多个文件，例如path/to/my/files/2.mp4 path/to/my/files/0.mp path/to/my/files/2.mp。

上传

要上传您的文件，请运行

arloader upload <FILE_PATHS>

这将启动从您的文件创建的流式传输包的上传过程。下面示例输出中的包大小为5000字节。

bundle txid                                   items      KB  status       confirms
------------------------------------------------------------------------------------
 QGPFcZq91lQgmmz2l7rQHkSQpgfJi-Vhv47oTqIYLm4       2       3  Submitted           0
 _-bhdsi4irDEWz8R9wXT-1c06WVQVSMAmQxVF9OkW94       2       3  Submitted           0
 -OAWdFiGS4NKOZXVJG3yZ0yN4xydGOhfQGX2FCdlG88       2       3  Submitted           0
 UBWGFKyTrUVaCa7wi_181FjAd545vdoHmBQEdlaVdA4       2       3  Submitted           0
 qzQlASZrQXNF9HYIOTPjEZL9uy1U9Ou086kCkQWqld0       2       3  Submitted           0

状态对象将被写入名为 <TXID>.json 的 json 文件，该文件位于 <FILE_PATHS> 中第一个文件的父目录下的新创建的子目录中。该文件夹将被命名为 arloader_<RAND_CHAR>。您可以通过传递 --log-dir 参数来指定一个现有的文件夹以写入状态。

{
    "id": "_-bhdsi4irDEWz8R9wXT-1c06WVQVSMAmQxVF9OkW94",
    "status": "Submitted",
    "file_paths": {
        "tests/fixtures/8.png": {
            "id": "0jd-NTQUZhmnKRY-kMt2vEcmSqgzKOLX_P3QYw6CaNE"
        },
        "tests/fixtures/9.png": {
            "id": "1XdiLkoZ5POHsNx7eLyRgisjnxTLzW8SxGsRcb22j84"
        }
    },
    "number_of_files": 2,
    "data_size": 3546,
    "created_at": "2021-11-23T05:47:41.948103600Z",
    "last_modified": "2021-11-23T05:47:41.948107100Z",
    "reward": 50947968
}

检查状态

上传您的文件后，您会想检查它们的状态，以确保它们已成功上传，并且最终至少确认了25次，您才能绝对确定它们已被永久上传。

arloader update-status <LOG_DIR>

这将读取 <LOG_DIR> 中的文件，寻找有效的交易 ID 作为文件名，然后前往网络以更新每个的状态。下面的示例包含两套包，一套仍在等待中，一套有45个确认。

bundle txid                                   items      KB  status       confirms
------------------------------------------------------------------------------------
 -OAWdFiGS4NKOZXVJG3yZ0yN4xydGOhfQGX2FCdlG88       2       3  Pending             0
 _-bhdsi4irDEWz8R9wXT-1c06WVQVSMAmQxVF9OkW94       2       3  Pending             0
 qzQlASZrQXNF9HYIOTPjEZL9uy1U9Ou086kCkQWqld0       2       3  Pending             0
 QGPFcZq91lQgmmz2l7rQHkSQpgfJi-Vhv47oTqIYLm4       2       3  Pending             0
 UBWGFKyTrUVaCa7wi_181FjAd545vdoHmBQEdlaVdA4       2       3  Pending             0
 KuuEZpbfCbw6izMeN3knWlpzmaFhnrDL9dUKCW2LQHw       2       3  Confirmed          45
 IRToYYvsftCiR71sfW5qt8XCzBFotwoDFBoEMEtrMrU       2       3  Confirmed          45
 M2QZYxUqw3ZJ2KXzU4pfw9fFIkVOSrJbSpE7NAvHLvo       2       3  Confirmed          45
 qvci4i6Mfr-5_NHI1bL-Omv16QEUw3iiirzv4fXefnM       2       3  Confirmed          45
 NAP2vTKQdMG_eKyKBYz3876T4yBFl4oYFYqwwwnHbFA       2       3  Confirmed          45

重新上传

如果您发现并非所有的交易都处于 Confirmed 状态，或者在一段时间后确认次数低于25次，您可能需要使用以下命令重新上传您的交易

arloader reupload <FILE_PATHS> --log-dir <LOG_DIR> --statuses <STATUSES> --max-confirmations <MAX_CONFIRMATIONS>

这将首先检查确保 <FILE_PATHS> 中的所有文件都包含在 <LOG_DIR> 中的状态对象中，并将它们添加到待重新上传的文件列表中。然后，它将根据 <STATUSES> 和 <MAX_CONFIRM> 过滤状态对象中的路径。您可以提供多个状态，只有确认次数少于 <MAX_CONFIRM> 的交易才会重新上传。

例如，如果您上传了大量位于 my/images 的 jpegs，并且状态已记录在 my/images/arloader_hehQJu-RJpo，如果您想重新上传状态为 NotFound 或 Pending 的交易，您将运行

arloader reupload my/images/*.jpeg --log-dir my/images/arloader_hehQJu-RJpo --statuses NotFound Pending

如果您想重新上传确认次数少于25次的任何内容，您将运行

arloader reupload my/images/*.jpeg --log-dir my/images/arloader_hehQJu-RJpo --max-confirms 25

创建清单

一旦您的文件的确认次数足够多，您可能想创建一个清单文件，该文件由 Arweave 网关用来提供对您的文件的相对路径。为了做到这一点，您运行

arloader upload-manifest <LOG_DIR>

其中 <LOG_DIR> 是包含您捆绑状态 json 文件的目录。这将会遍历并合并每个捆绑的路径，创建一个合并的清单，上传到 Arweave，然后将名为 manifest_<TXID>.json 的文件写入到 <LOG_DIR>。一旦清单上传交易被确认，您将能够访问您的文件，并且可以通过 https://arweave.net/<BUNDLE_ITEM_ID> 和 https://arweave.net/<MANIFEST_ID>/<FILE_PATH> 访问，其中 MANIFEST_ID 是清单交易的 ID，FILE_PATH 是 upload 命令包含的文件的相对路径。

{
    "tests/fixtures/0.png": {
        "files": [
            {
                "type": "image/png",
                "uri": "https://arweave.net/BSvIAiwthQu_xwQBHn9FcgACaZ8ko4py5mqMNP4r-jM/tests/fixtures/0.png"
            },
            {
                "type": "image/png",
                "uri": "https://arweave.net/JQbz5py065lqaS_8R7NCtLcK2b-pSkkG6Je0OT8379c"
            }
        ],
        "id": "JQbz5py065lqaS_8R7NCtLcK2b-pSkkG6Je0OT8379c"
    },
    "tests/fixtures/1.png": {
        "files": [
            {
                "type": "image/png",
                "uri": "https://arweave.net/BSvIAiwthQu_xwQBHn9FcgACaZ8ko4py5mqMNP4r-jM/tests/fixtures/1.png"
            },
            {
                "type": "image/png",
                "uri": "https://arweave.net/Os-tEyRqdjwwyNo1mpLaPGu8_r3KbV-iNRH-aPtJFOw"
            }
        ],
        "id": "Os-tEyRqdjwwyNo1mpLaPGu8_r3KbV-iNRH-aPtJFOw"
    },

您可以使用以下命令来获取您清单交易的状态更新。

arloader get-status <MANIFEST_ID>

SOL 一起使用

您可以使用 SOL 来支付您的交易，而无需繁琐地获取 AR 代币。

Arloader 的使用方法几乎与上述相同，只是增加了 --with-sol 标志。

  1. 要估算上传您的文件的成本，请运行
arloader estimate <FILE_PATHS> --with-sol
  1. 要上传您的文件，请运行
arloader upload <FILE_PATHS> --with sol --ar-default-keypair

这将会创建与不使用 SOL 创建的相同捆绑流，然后发送到 api 以获取您的交易签名。一旦 SOL 支付交易通过，签名将从 api 返回并添加到您的捆绑交易中。然后，交易将从您的计算机直接上传到 arweave.net 网关。

奖励倍数

Arweave 每两分钟限制约 1,000 笔交易，因此如果您在有许多待处理交易的时候提交交易，它可能需要更长的时间来写入，或者如果有更多具有更高奖励的交易，它可能根本无法写入。要检查当前待处理交易的数目，运行

arloader pending

这将每秒打印一分钟的待处理交易数量。

 pending tx
-------------------------------------------------------------------------------------------------
  118 | ▥▥▥
  123 | ▥▥▥
  124 | ▥▥▥
  224 | ▥▥▥▥▥
  125 | ▥▥▥
  326 | ▥▥▥▥▥▥▥
  128 | ▥▥▥

鉴于 Arloader 默认捆绑，您的交易希望相对有吸引力，您不需要增加奖励来及时写入。然而，如果您看到有很多待处理交易，并且您想确保您的交易快速通过，您可以使用 --reward-multiplier 调整奖励，后面跟着可以在 0.0 和 3.0 之间解析为浮点数的东西。提交时，您的交易中包含的奖励将乘以这个因子。类似于 --with-sol 标志，您可以将 --reward-multiplier 添加到 estimate 和 upload 命令。

无捆绑使用

如果您出于某种原因想创建单个交易，可以添加 --no-bundle 标志。这适用于 estimate 和 upload 命令。在这种情况下，单独的状态对象将被写入到 <LOG_DIR>，并且您可以通过运行 update-status 来从网络更新它们，以及通过 status-report 来按状态统计交易数量。

基准测试

下表显示了创建不同文件大小和文件数量范围的交易的平均所需时间。详细的统计分析图表可以在 此处 找到（数字可能与以下数字略有不同）。

对于拥有10,000个代币的NFT项目，如果图片大小为256 KB，处理图片将需要20秒。如果图片大小为4 MB，则大约需要两分钟。

文件大小 文件数量 总大小 数据项 数据项 包 交易 总计 每1000个
32 KB 500 16 4 430 30 40 0.5 1.0
256 KB 500 128 4 493 179 326 1.0 2.0
1 MB 500 512 5 616 903 1033 2.6 4.1
4 MB 150 614 11 360 1050 1554 3.0 10.4
16 MB 50 819 35 393 1403 2058 3.9 77.1

基准测试仅包括处理活动，不包括从磁盘读取文件并将其上传到网络。基准测试在Intel(R) Core(TM) i7-8750H CPU @ 2.20GHz处理器上，具有6个核心的机器上进行。

列 描述
总大小 文件大小（兆字节）乘以文件数量。
数据项 创建单个数据项所需的时间（毫秒）。这包括创建默克尔树数据根、从深度哈希算法生成ID并对其进行签名。
数据项 为文件数量创建数据项所需的时间（毫秒）。数据项将使用所有可用核心并行处理。
包 从数据项创建单个包所需的时间（毫秒）。这包括序列化每个数据项并将它们打包在一起。
交易 从包创建单个交易所需的时间（毫秒）。这包括创建默克尔树数据根、从深度哈希算法生成ID并对其进行签名。
总计 创建数据项、包和交易所需的总时间（秒）。
每1000个 将总计外推到1000个文件。

定价比较

下表比较了将256 MB的文件作为单个文件上传到Arweave的成本与单个包上传的成本，以及与bundlr网络的比较。这是在2021-12-17运行的。您可以通过运行cargo run --example pricing来打印包含当前价格的表格。

Price in USD to upload 256 MB of files of various sizes in KB ($48.33 USD per AR):

file size | num files | arweave | bundlr | arweave total | bundlr total | arweave bundle
-----------------------------------------------------------------------------------------
        1      262144    0.0019   0.0000        508.3164         5.1784           1.9616
       32        8192    0.0019   0.0003         15.8849         2.5892           1.9616
      256        1024    0.0019   0.0025          1.9856         2.5892           1.9616
     1024         256    0.0077   0.0101          1.9676         2.5892           1.9616
     4096          64    0.0307   0.0405          1.9631         2.5892           1.9616
    16384          16    0.1226   0.1618          1.9620         2.5892           1.9616

路线图

  • 包大小单位为MB
  • 处理定价查找错误
  • 流后缓冲块
  • 添加上传NFT项目示例
  • 指向资产和json文件夹，获取上传元数据的链接
  • 清理路径处理
  • 重新上传包
  • 添加简单的单次上传，返回链接
  • 较长运行过程的进度指示器
  • 以metaboss格式输出，或包含在metaplex cli中
  • 实现bundlr
  • 异步基准测试，包括从磁盘读取文件
  • bundlr基准测试
  • 在list-status和update-status命令中报告丢失的文件
  • 在完成输出中包含持续时间。

版本0.1.51之前上传的交易潜在问题

arloader格式化上传交易的方式在版本1.51之前并不完全与Arweave协议兼容。对于大于256 KB的交易，即使您的交易可见并且显示超过25个确认，它们也可能没有被写入Arweave区块链。如果您想确定您的交易是否受到影响，请打开一个问题，我会很高兴帮助，包括支付任何必要的重新上传费用。

依赖项

~35–50MB
~1M SLoC