atlas-poseidon 0.1.1

Atlas Poseidon hashing
Documentation

atlas-poseidon

Crates.io Documentation License

Atlas Poseidon hashing library for zero-knowledge proof systems and blockchain applications.

Overview

This crate provides an implementation of the Poseidon hash function, optimized for use in zero-knowledge proof systems. Poseidon is a cryptographic hash function designed specifically for efficient use in zkSNARKs and other advanced cryptographic protocols.

Features

  • BN254 curve support - Optimized for the BN254 elliptic curve
  • Multiple endianness - Support for both big-endian and little-endian byte ordering
  • No-std compatible - Can be used in embedded and no_std environments
  • Atlas integration - Native syscall support when running on Atlas Chain
  • Legacy compatibility - Backward compatible API with older versions

Installation

Add this to your Cargo.toml:

[dependencies]
atlas-poseidon = "0.1.0"

For unstable API usage (required from v4.0.0 onward):

[dependencies]
atlas-poseidon = { version = "0.1.0", features = ["atlas-unstable-api"] }

Usage

Basic Hashing

Hash a single 32-byte input:

use atlas_poseidon::{hash, Parameters, Endianness};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = [1u8; 32];
    let hash_result = hash(
        Parameters::Bn254X5,
        Endianness::BigEndian,
        &input
    )?;

    println!("Hash: {:?}", hash_result.to_bytes());
    Ok(())
}

Hashing Multiple Inputs

Hash multiple inputs together:

use atlas_poseidon::{hashv, Parameters, Endianness};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input1 = [1u8; 32];
    let input2 = [2u8; 32];

    let hash_result = hashv(
        Parameters::Bn254X5,
        Endianness::BigEndian,
        &[&input1, &input2]
    )?;

    println!("Hash: {:?}", hash_result.to_bytes());
    Ok(())
}

Endianness

The library supports both big-endian and little-endian byte ordering:

use atlas_poseidon::{hash, Parameters, Endianness};

let input = [1u8; 32];

// Big-endian
let hash_be = hash(Parameters::Bn254X5, Endianness::BigEndian, &input)?;

// Little-endian
let hash_le = hash(Parameters::Bn254X5, Endianness::LittleEndian, &input)?;

API

Main Functions

  • hash(parameters, endianness, data) - Hash a single input
  • hashv(parameters, endianness, inputs) - Hash multiple inputs

Parameters

  • Parameters::Bn254X5 - BN254 curve with x^5 S-box (currently the only supported parameter)

Endianness

  • Endianness::BigEndian - Big-endian byte ordering
  • Endianness::LittleEndian - Little-endian byte ordering

Error Handling

The library provides detailed error types through PoseidonSyscallError:

  • InvalidNumberOfInputs - Maximum of 12 inputs allowed
  • InvalidInputLength - Input length must match the prime field modulus (32 bytes)
  • InputLargerThanModulus - Input value exceeds the prime field modulus
  • And more...

Platform Support

This crate works on both standard platforms and the Atlas Chain:

  • Standard platforms: Uses the light-poseidon and ark-bn254 libraries for computation
  • Atlas Chain: Uses native syscalls for optimized performance

Legacy API

For compatibility with older code, a legacy API is available in the legacy module. See the documentation for details.

License

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

Contributing

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

Resources