arweave-unbundle

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

• Clone the repository:

git clone <repository-url>
cd unbundle-ans104

• Install dependencies:

npm install

• 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:

• Use a known valid Arweave bundle ID
• Test invalid IDs for validation
• Test network error handling by disconnecting internet
• 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:

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

Troubleshooting

Common Issues

• "Cannot reach Arweave network"

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

• "Bundle not found with ID"

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

• "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

• "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:

• Fork the repository
• Create a feature branch
• Add tests for new functionality
• 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