Base64 Encoding Library for Sway

A complete Base64 encoding implementation for the Sway programming language on the Fuel blockchain network. This library provides both standard and URL-safe Base64 encoding functionality following RFC 4648 specifications.

Overview

This library implements Base64 encoding algorithms in pure Sway, providing developers with essential data encoding capabilities for smart contracts and blockchain applications on the Fuel network.

Features

• Standard Base64 Encoding: Implements RFC 4648 Section 4 with A-Za-z0-9+/ alphabet and padding
• URL-Safe Base64 Encoding: Implements RFC 4648 Section 5 with A-Za-z0-9-_ alphabet without padding
• Memory Safety: Built-in input validation to prevent overflow conditions
• Comprehensive Testing: Extensive test suite with 17 test cases covering edge cases and standard compliance
• Performance Optimized: Efficient bit manipulation operations for high-performance encoding

Installation

Add this library to your Forc.toml dependencies:

forc add base64

[dependencies]
base64 = "0.1.0"

API Reference

Functions

encode(data: Vec<u8>) -> String

Encodes a byte vector into a standard Base64 string with padding.

Parameters:

• data: A vector of bytes to encode

Returns:

• A Base64-encoded string using the standard alphabet with appropriate padding

Example:

let data = Vec::from([77u8, 97u8, 110u8]); // "Man"
let encoded = encode(data); // Returns "TWFu"

encode_url(data: Vec<u8>) -> String

Encodes a byte vector into a URL-safe Base64 string without padding.

Parameters:

• data: A vector of bytes to encode

Returns:

• A URL-safe Base64-encoded string without padding characters

Example:

let data = Vec::from([77u8]); // "M"
let encoded = encode_url(data); // Returns "TQ"

Usage Examples

Basic Encoding

use base64::{encode, encode_url};

// Standard Base64 encoding
let mut data: Vec<u8> = Vec::new();
data.push(72u8);  // 'H'
data.push(101u8); // 'e'
data.push(108u8); // 'l'
data.push(108u8); // 'l'
data.push(111u8); // 'o'

let standard_encoded = encode(data); // "SGVsbG8="
let url_safe_encoded = encode_url(data); // "SGVsbG8"

Encoding String Data

// Encoding "Build with Sway"
let data = Vec::from([
    66u8, 117u8, 105u8, 108u8, 100u8, 32u8, 119u8, 105u8, 
    116u8, 104u8, 32u8, 83u8, 119u8, 97u8, 121u8
]);

let encoded = encode(data); // "QnVpbGQgd2l0aCBTd2F5"

Technical Specifications

Encoding Process

The library implements the standard Base64 encoding algorithm:

1. Input Processing: Processes input data in 3-byte chunks
2. Bit Manipulation: Combines 3 bytes into a 24-bit value
3. Character Extraction: Extracts four 6-bit indices for alphabet lookup
4. Alphabet Mapping: Maps indices to Base64 characters using predefined tables
5. Padding: Applies appropriate padding for standard encoding

Memory Safety

• Input size validation prevents integer overflow conditions
• Safe array indexing with bounds checking
• Efficient memory allocation using Sway's standard library collections

Performance Characteristics

• Time Complexity: O(n) where n is the input size
• Space Complexity: O(4n/3) for output buffer allocation
• Bit Operations: Optimized shift and mask operations for character extraction

Testing

The library includes comprehensive testing covering:

• Empty input handling
• Single, double, and triple byte encoding
• Padding verification for standard encoding
• URL-safe encoding without padding
• Binary data encoding
• Special character handling
• Input validation edge cases

Run tests using:

forc test

Standards Compliance

This implementation strictly follows:

• RFC 4648 Section 4: Standard Base64 encoding with padding
• RFC 4648 Section 5: URL and filename safe Base64 encoding without padding

Limitations

• Encoding Only: This library provides encoding functionality only
• UTF-8 Input: Input must be provided as byte vectors
• Size Constraints: Maximum input size limited by u64 arithmetic to prevent overflow

Credits

This implementation draws inspiration from established Base64 encoding algorithms and follows the mathematical foundations laid out in RFC 4648. The bit manipulation techniques are adapted from standard implementations found in various programming languages and cryptographic libraries.

License

This project is provided as-is for educational and development purposes.