ethereum-walrus-sdk

v1.0.2

Published

8 months ago

Production-ready TypeScript SDK for integrating Ethereum smart contracts with Walrus decentralized storage

🐋 Ethereum Walrus SDK

A production-ready TypeScript SDK that seamlessly integrates Ethereum smart contracts with Walrus decentralized storage. Upload encrypted files to Walrus and store references on Ethereum with just a few lines of code.

✨ Features

🔐 End-to-End Encryption: AES-256-GCM encryption for client-side data security
🌐 Decentralized Storage: Seamless integration with Walrus storage network
⛓️ Ethereum Integration: Store blob references on Ethereum smart contracts
📦 Easy to Use: Simple API with comprehensive TypeScript support
🧪 Production Ready: Comprehensive testing and error handling
🔧 Flexible: Works in both browser and Node.js environments
📱 dApp Friendly: Perfect for decentralized applications

🚀 Quick Start

Installation

npm install ethereum-walrus-sdk ethers

Basic Usage

``typescript import { EthereumWalrusSDK } from 'ethereum-walrus-sdk'; import { ethers } from 'ethers';

// Setup const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL'); const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Initialize SDK const sdk = new EthereumWalrusSDK({ walrus: { aggregatorUrl: 'https://aggregator.walrus-testnet.walrus.space', publisherUrl: 'https://publisher.walrus-testnet.walrus.space' }, debug: true }, provider, signer);

// Upload file to Walrus and store reference on Ethereum const file = new Uint8Array(Buffer.from('Hello, Walrus!')); const contractConfig = { address: '0x...', // Your deployed contract address abi: [...] // Your contract ABI };

const { blobId, transactionReceipt } = await sdk.uploadAndStore( file, contractConfig, signer );

console.log('File uploaded and reference stored!'); console.log('Blob ID:', blobId); console.log('Transaction:', transactionReceipt.hash);


## 📚 Comprehensive Documentation

For detailed documentation, please see our [Documentation Directory](docs/README.md) which includes:

### Core Documentation
- [📚 API Reference](docs/api/README.md) - Complete documentation for all classes and methods
- [📖 Installation Guides](docs/guides/installation.md) - Step-by-step installation instructions
- [🔧 Usage Guides](docs/guides/) - Environment-specific usage instructions (Node.js, Browser, React)
- [💡 Examples](docs/examples/README.md) - Practical code examples and tutorials

### Advanced Topics
- [🔗 Smart Contracts](docs/contracts/README.md) - Documentation for example contracts and deployment
- [🔒 Security](docs/security/README.md) - Security best practices and guidelines
- [🛠️ Troubleshooting](docs/troubleshooting/README.md) - Solutions to common issues and FAQ
- [⚡ Performance](docs/performance/README.md) - Optimization techniques and best practices

### Project Resources
- [🔄 Migration](docs/migration/README.md) - Version upgrade guides
- [🤝 Contributing](docs/contributing/README.md) - How to contribute to the project
- [📖 Documentation Index](docs/index.md) - Complete documentation index
- [📋 Project Summary](PROJECT_SUMMARY.md) - Detailed project overview

## 📖 Documentation Structure

docs/ ├── README.md # Main documentation index ├── index.md # Quick navigation index ├── overview.md # Comprehensive overview ├── api/ # API reference documentation ├── guides/ # Installation and usage guides ├── examples/ # Practical examples and tutorials ├── contracts/ # Smart contract documentation ├── security/ # Security best practices ├── troubleshooting/ # Troubleshooting guides ├── performance/ # Performance optimization ├── migration/ # Version migration guides └── contributing/ # Contribution guidelines


## 🎯 Key Components

### Main SDK Class
The [EthereumWalrusSDK](docs/api/classes/EthereumWalrusSDK.md) is the primary interface for most applications:

```typescript
// Core methods
sdk.uploadBlob(data, options)           // Upload encrypted data to Walrus
sdk.storeBlobReference(blobId, ...)     // Store reference on Ethereum
sdk.retrieveBlob(blobId, options)       // Retrieve and decrypt data
sdk.getBlobReference(...)               // Get blob ID from contract
sdk.uploadAndStore(data, ...)           // Combined upload and store
sdk.retrieveFromContract(...)           // Combined retrieve operation

Example Smart Contracts

SimpleWalrusStorage - Minimal single-blob storage
WalrusBlobStorage - Full-featured multi-user storage

Environment Support

Node.js Usage - Server-side applications
Browser Usage - Client-side web applications
React Usage - React applications

🔧 Development

Building from Source

# Clone the repository
git clone https://github.com/your-org/ethereum-walrus-sdk.git
cd ethereum-walrus-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development mode
npm run build:watch

Project Structure

ethereumwalrus-sdk/
├── src/                   # Source code
│   ├── types/             # TypeScript interfaces
│   ├── utils/             # Utility functions
│   ├── clients/           # Walrus and Ethereum clients
│   ├── sdk.ts             # Main SDK class
│   └── index.ts           # Public exports
├── contracts/             # Example smart contracts
├── examples/              # Usage examples
├── tests/                 # Test suites
├── docs/                  # Documentation
└── scripts/               # Utility scripts

🧪 Testing

Run the comprehensive test suite:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Test coverage:

Statement: 95%
Branch: 90%
Function: 98%
Line: 94%

📋 Requirements

Runtime

Node.js: 16.0.0 or higher
TypeScript: 5.0 or higher (for development)
Ethers.js: 6.0 or higher
Modern Browser: Chrome 88+, Firefox 85+, Safari 14+

Development

npm: 7.0.0 or higher
Git: For version control
Ethereum Wallet: For testing (MetaMask, etc.)
Walrus Testnet Access: For decentralized storage testing

🚧 Roadmap

[ ] Multi-chain support for additional blockchains
[ ] IPFS integration as alternative storage option
[ ] Mobile SDKs for React Native and Flutter
[ ] Advanced encryption with post-quantum cryptography
[ ] Caching layer for frequently accessed files
[ ] Built-in file compression options
[ ] Streaming support for large file handling

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# Fork and clone the repo
git clone https://github.com/your-username/ethereum-walrus-sdk.git

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and test
npm test
npm run build

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Create a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Walrus: For providing decentralized storage infrastructure
Ethereum: For the blockchain foundation
Ethers.js: For the excellent Ethereum library
TypeScript: For making JavaScript development better

📞 Support

Documentation: docs/README.md - Complete documentation
Examples: docs/examples/README.md - Practical examples
API Reference: docs/api/README.md - Detailed API documentation
Issues: GitHub Issues - Bug reports
Discussions: GitHub Discussions - Questions
Discord: Join our community - Real-time support

Made with ❤️ for the decentralized future

Website • Documentation • Examples • GitHub