Arweave Data Unbundler CLI

A command-line interface tool for downloading and unbundling Arweave ANS-104 data bundles. This tool retrieves raw data from the Arweave network, unbundles it using the @dha-team/arbundles package, extracts exactly two data items, and saves them as JSON.

Features

• ✅ Downloads raw data from Arweave network
• ✅ Validates 43-character Arweave transaction IDs
• ✅ Unbundles ANS-104 data using @dha-team/arbundles
• ✅ Extracts and processes exactly 2 data items
• ✅ Converts data to JSON format (with base64 fallback for binary data)
• ✅ Comprehensive error handling and user feedback
• ✅ Cross-platform compatibility (Windows, macOS, Linux)

Prerequisites

• Node.js (v14 or higher)
• npm (v6 or higher)
• Internet connection to access Arweave network

Installation

From Source

1. Clone the repository:

git clone <repository-url>
cd unbundle-ans104

2. Install dependencies:

npm install

3. Make the CLI globally available:

npm link

Local Usage

If you prefer not to install globally, you can run directly:

node cli.js <arweave-id>

Usage

Basic Usage

Unbundle an Arweave data bundle:

arweave-unbundler <arweave-id>

Example:

arweave-unbundler 1234567890123456789012345678901234567890123

Custom Output File

Specify a custom output file path:

arweave-unbundler <arweave-id> --output custom-output.json

Validate Arweave ID

Check if an Arweave ID is valid without downloading:

arweave-unbundler validate <arweave-id>

Help

Display help information:

arweave-unbundler --help

Output Format

The tool generates a JSON file with the following structure:

[
  {
    "id": "item-id",
    "signature": "item-signature",
    "owner": "owner-address",
    "target": "target-address or null",
    "anchor": "anchor or null",
    "tags": [
      {
        "name": "tag-name",
        "value": "tag-value"
      }
    ],
    "data": {
      "your": "json-data"
    }
  },
  {
    "id": "second-item-id",
    "signature": "second-item-signature",
    "owner": "second-owner-address",
    "target": null,
    "anchor": null,
    "tags": [],
    "data": {
      "_type": "binary",
      "_encoding": "base64",
      "data": "base64-encoded-binary-data"
    }
  }
]

Binary Data Handling

If a data item contains binary data that cannot be parsed as JSON, it will be encoded as base64 with the following structure:

{
  "_type": "binary",
  "_encoding": "base64",
  "data": "base64-encoded-content"
}

Error Handling

The CLI provides detailed error messages for common issues:

• Invalid ID Format: Checks for exactly 43 characters with valid characters
• Network Errors: Connection timeouts, DNS failures, server errors
• Bundle Errors: Invalid ANS-104 format, unsupported versions
• Data Errors: Insufficient items in bundle (less than 2)
• File System Errors: Permission issues, disk space

Examples

Example 1: Basic Unbundling

$ arweave-unbundler ABC123_-abc123_-abc123_-abc123_-abc123_-ab
Starting unbundle process for ID: ABC123_-abc123_-abc123_-abc123_-abc123_-ab
Downloading bundle from: https://arweave.net/raw/ABC123_-abc123_-abc123_-abc123_-abc123_-ab
Downloaded 45632 bytes
Parsing bundle...
Found 2 items in bundle
Processing item 1/2...
Processing item 2/2...
Successfully wrote output to: output.json

Unbundle completed successfully in 2.34s
Extracted 2 items to: /path/to/output.json

Example 2: ID Validation

$ arweave-unbundler validate invalid-id
✗ Invalid Arweave ID: Invalid Arweave ID length. Expected 43 characters, got 10

Example 3: Custom Output

$ arweave-unbundler ABC123_-abc123_-abc123_-abc123_-abc123_-ab --output results/bundle.json
Starting unbundle process for ID: ABC123_-abc123_-abc123_-abc123_-abc123_-ab
...
Successfully wrote output to: results/bundle.json

Development

Running Tests

Currently, the project includes manual testing scenarios. To test:

1. Use a known valid Arweave bundle ID
2. Test invalid IDs for validation
3. Test network error handling by disconnecting internet
4. Test file permissions by writing to protected directories

Project Structure

unbundle-ans104/
├── cli.js          # Main CLI implementation
├── package.json    # Project configuration
├── README.md       # This file
└── output.json     # Default output file (generated)

Adding Features

The code is structured for easy extension:

1. Validation: Add new validation rules in validateArweaveId()
2. Processing: Modify data extraction in unbundleData()
3. Output Formats: Add new formatters before writeOutput()

Troubleshooting

Common Issues

1. "Cannot reach Arweave network"

   • Check your internet connection
   • Verify firewall settings allow HTTPS connections

2. "Bundle not found with ID"

   • Verify the Arweave ID is correct
   • Ensure the transaction contains an ANS-104 bundle

3. "Expected at least 2 items in bundle"

   • The bundle must contain at least 2 data items
   • This tool is specifically designed for 2-item bundles

4. "Permission denied writing to"

   • Ensure you have write permissions in the output directory
   • Try using a different output path with --output

Security

• Input validation prevents injection attacks
• No sensitive data is logged or exposed
• Network requests use HTTPS only
• File operations use safe path resolution

License

ISC License - see package.json for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Support

For issues or questions:

• Check the troubleshooting section
• Review error messages for specific guidance
• Open an issue in the project repository