Decentralized Decision Library

A library for decentralized decision making, fair division algorithms, and random number generation. This library focuses on consensus-friendly, objective algorithms.

Features

⚖️ Fair Division Algorithms

• Equal weights and weighted fair division
• Super fair division algorithms
• Optimal resource allocation

🎲 Decentralized Random Number Generation

• Single and multiple random number generation
• Collision resistance and uniqueness guarantees
• Offset mechanism for pattern prevention

Installation

Add this to your Cargo.toml:

[dependencies]
dd_algorithms_lib = "0.1.0"

Basic Usage

use dd_algorithms_lib::{
    // Fair Division
    calculate_fair_division_equal_weights,
    calculate_fair_division_weighted,
    
    // Random Generation
    get_one_dd_rand_num,
    get_k_dd_rand_num,
};

// Fair division example
let bids = [100i128, 200, 300];
let mut allocation = [0i128; 3];
calculate_fair_division_equal_weights(&bids, &mut allocation).unwrap();
// allocation: [66, 133, -199] (sum = 0)

// Random selection example
let group1 = [100u128, 200, 300];
let group2 = [150u128, 250, 350];
let group3 = [120u128, 220, 320];
let groups = [group1.as_slice(), group2.as_slice(), group3.as_slice()];
let mut selected = [0usize; 3];
get_k_dd_rand_num(&groups, 3, 3, &mut selected).unwrap();
// selected: [1, 2, 0] (unique participant indices)

Modules

algorithms

Mathematical algorithms for fair division and random number generation:

• calculate_fair_division_equal_weights() - Fair division with equal weights
• calculate_fair_division_weighted() - Fair division with custom weights
• get_one_dd_rand_num() - Generate single decentralized random number
• get_k_dd_rand_num() - Generate multiple unique random numbers

types

Common data types and enums:

• VotingPower - Voting power type alias
• ParticipantId - Participant identifier type
• Timestamp - Timestamp type alias
• FairDivisionResult - Result structure for fair division (if used)
• RandomSelectionResult - Result structure for random selection (if used)

Algorithm Details

Fair Division

Implements super fair division algorithms that ensure:

• Zero-sum allocations (sum of all allocations equals zero)
• Fair distribution based on input values or weights
• Optimal resource allocation

Random Number Generation

Decentralized random number generation with:

• Collision Resistance: Ensures all generated numbers are unique
• Unpredictability: Uses participant-provided random values
• Offset Mechanism: Prevents patterns through systematic offsetting
• Validation: Comprehensive parameter validation and bounds checking

Examples

See the examples/ directory for comprehensive usage examples:

• governance_example.rs - Complete demonstration of all features
• function_names_test.rs - Function name verification and testing

Constraints

• Participants (n): ≤ 100,000
• Selections (k): ≤ 1,000
• k ≤ n: Cannot select more participants than available

License

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

Contributing

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

Publishing to crates.io

Follow this checklist to publish a new version of this crate to crates.io.

1) Prerequisites

• Create and verify a crates.io account
• (Recommended) Enable 2FA on crates.io
• Create an API token on crates.io → Account → API Tokens
• Login locally:

cargo login <YOUR_API_TOKEN>

2) Verify Cargo.toml metadata

Ensure the following fields are correct: name, version, description, license, repository, documentation, readme, keywords, categories, rust-version. This crate defaults to no_std and offers optional std, serde, and log_tests features.

3) Build, test, docs

cargo clean
cargo test
# Optional: show test logs
cargo test --features log_tests -- --nocapture
# Local docs
cargo doc --no-deps

4) Package and dry run

cargo package
cargo publish --dry-run

5) Publish

cargo publish

6) Versioning and tags

# Bump version in Cargo.toml first
git tag -a v0.1.0 -m "Release v0.1.0"
git push --tags

7) Manage owners

cargo owner --add <github-user-or-team>
cargo owner --list

8) Troubleshooting

• If packaged content is wrong, inspect with cargo package and adjust include/exclude in Cargo.toml or .gitignore.
• For no_std docs on docs.rs, ensure default features don’t pull in std. This crate uses #![no_std] by default.
• Printing in tests is gated behind the optional log_tests feature to keep default no_std behavior.

9) Releasing fixes

Crates cannot be overwritten. Bump the version and republish. You can yank a bad version:

cargo yank --vers <version>
# Undo if necessary
cargo yank --vers <version> --undo