Züs Storage HTTP Gateway

A Go-based HTTP gateway providing REST API access to the Züs decentralized storage network. This microservice enables developers to integrate Züs storage capabilities into applications written in any programming language through simple HTTP requests.

Features

• Language Agnostic: Integrate Züs storage from JavaScript, Python, Ruby, or any language with HTTP support
• Reliable: Built on the stable Züs gosdk
• Secure: Credentials managed server-side, never exposed to clients
• Simple REST API: Easy-to-use HTTP endpoints for storage operations

API Endpoints

Initialize SDK

POST /init-sdk

Initializes the Züs SDK with wallet credentials and network configuration.

Upload File

POST /upload-file
Content-Type: application/json

{
  "allocation_id": "your-allocation-id",
  "local_path": "/path/to/file.jpg",
  "encrypt": true,
  "web_streaming": false
}

Uploads a file to the Züs network and returns an auth ticket for sharing.

Download File

POST /download-file
Content-Type: application/json

{
  "allocation_id": "your-allocation-id",
  "filename": "file.jpg",
  "auth_ticket": "auth-ticket-string",
  "local_path": "/path/to/save/file.jpg"
}

Downloads a file from the Züs network using an auth ticket.

Prerequisites

• Go 1.23.4 or higher
• Züs wallet (create one at using zwalletcli
• Züs allocation ID (create one using zboxcli

Setup

1. Clone the repository

   git clone https://github.com/YOUR_USERNAME/zus-storage-api.git
   cd zus-storage-api

2. Install dependencies

   go mod download

3. Configure credentials

   The service uses config.yaml for configuration. An example is provided in config.example.yaml.

   For wallet configuration, you'll need to set up your Züs wallet separately and ensure the SDK can access it from ~/.zcn/ directory.

4. Run the service

   go run main.go

   The service will start on http://localhost:8080

Usage Example

JavaScript/Node.js

// Initialize SDK
const initResponse = await fetch('http://localhost:8080/init-sdk', {
  method: 'POST'
});

// Upload a file
const uploadResponse = await fetch('http://localhost:8080/upload-file', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    allocation_id: 'your-allocation-id',
    local_path: './photo.jpg',
    encrypt: true,
    web_streaming: false
  })
});

const { auth_ticket } = await uploadResponse.json();
console.log('File uploaded! Auth ticket:', auth_ticket);

Python

import requests

# Initialize SDK
requests.post('http://localhost:8080/init-sdk')

# Upload a file
response = requests.post('http://localhost:8080/upload-file', json={
    'allocation_id': 'your-allocation-id',
    'local_path': './photo.jpg',
    'encrypt': True,
    'web_streaming': False
})

auth_ticket = response.json()['auth_ticket']
print(f'File uploaded! Auth ticket: {auth_ticket}')

cURL

# Initialize SDK
curl -X POST http://localhost:8080/init-sdk

# Upload a file
curl -X POST http://localhost:8080/upload-file \
  -H "Content-Type: application/json" \
  -d '{
    "allocation_id": "your-allocation-id",
    "local_path": "./photo.jpg",
    "encrypt": true,
    "web_streaming": false
  }'

Configuration

The config.yaml file contains network and SDK settings:

• block_worker: Züs network DNS endpoint
• chain_id: Blockchain network identifier
• signature_scheme: Cryptographic signature scheme (bls0chain)
• min_submit: Minimum blobbers for submission
• min_confirmation: Minimum confirmations required
• confirmation_chain_length: Chain length for confirmations
• sharder_consensous: Sharder consensus requirement
• max_txn_query: Maximum transaction queries
• query_sleep_time: Query sleep time in seconds

Project Structure

.
├── main.go                 # HTTP server and route configuration
├── handlers/
│   ├── sdk_handler.go     # SDK initialization endpoint
│   ├── upload_handler.go  # File upload endpoint
│   └── download_handler.go # File download endpoint
├── config.yaml             # Network configuration
├── config.example.yaml     # Configuration template
└── README.md

Use Cases

• Web Applications: Backend API for browser-based file storage
• Data Pipelines: Python/Ruby scripts storing data on Züs
• Mobile Apps: iOS/Android apps integrating decentralized storage
• Enterprise Systems: Multi-language environments requiring Züs integration

Security Considerations

• Store wallet files securely in ~/.zcn/ directory
• Use HTTPS in production deployments
• Implement authentication/authorization for production use
• Consider rate limiting for public-facing deployments
• Never expose wallet credentials to clients

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See LICENSE file for details.

Resources

• Züs Network
• Züs Go SDK Documentation
• Züs Developer Portal

Support

For issues and questions:

• Open an issue on GitHub
• Visit Züs Discord