Implement Branch Contract

[gelluisaac]

closes #248 This PR introduces a comprehensive branch management system to the AssetsUp Soroban contract, enabling organizations to organize and manage their assets across multiple branches/locations.

🚀 Features Added

Core Branch Management

• Branch Creation: Create new branches with unique IDs, names, locations, and designated admins
• Asset Linking: Associate assets with specific branches for better organization
• Branch Retrieval: Query branch information and associated assets
• Admin Access Control: Enforce admin-only permissions for branch creation

Data Structures

• Branch Struct: Contains id, name, location, and admin fields
• DataKey Enum: Supports Branch(BytesN<32>) and AssetList(BytesN<32>) storage keys
• Asset List Management: Automatic initialization and management of asset lists per branch

🔧 Technical Implementation

New Files

• src/branch.rs - Branch data structures and types
• src/tests/branch.rs - Comprehensive test suite (8 test cases)

Modified Files

• src/lib.rs - Added branch module and 4 new contract functions
• src/errors.rs - Added 3 new error types for branch operations
• src/tests/mod.rs - Included branch tests module

New Contract Functions

pub fn create_branch(env: Env, id: BytesN<32>, name: String, location: String, admin: Address) -> Result<(), ContractError>
pub fn add_asset_to_branch(env: Env, branch_id: BytesN<32>, asset_id: BytesN<32>) -> Result<(), ContractError>
pub fn get_branch_assets(env: Env, branch_id: BytesN<32>) -> Result<Vec<BytesN<32>>, ContractError>
pub fn get_branch(env: Env, branch_id: BytesN<32>) -> Result<Branch, ContractError>

🛡️ Security & Access Control

• Admin Authentication: Only contract admins can create new branches
• Input Validation: Branch names cannot be empty
• Duplicate Prevention: Prevents creation of branches with duplicate IDs
• Asset Verification: Ensures assets exist before linking to branches

🧪 Testing

Test Coverage

• ✅ Branch creation and retrieval
• ✅ Duplicate branch prevention
• ✅ Empty name validation
• ✅ Asset linking to branches
• ✅ Error handling for non-existent entities
• ✅ Multiple asset management
• ✅ Duplicate asset handling

Test Results

running 14 tests
test result: ok. 14 passed; 0 failed; 0 ignored; 0 measured

📊 Error Handling

New Error Types

• BranchAlreadyExists = 3 - Attempted to create duplicate branch
• BranchNotFound = 4 - Referenced branch doesn't exist
• Unauthorized = 5 - Insufficient permissions for operation

🔄 Integration

• Seamless Integration: Works alongside existing asset management system
• Backward Compatibility: No breaking changes to existing functionality
• Storage Efficiency: Uses persistent storage with optimized key structure
• Type Safety: Full Soroban contract type safety with proper serialization

📝 Usage Examples

Create a Branch

let branch_id = BytesN::from_array(&env, &[1u8; 32]);
let name = String::from_str(&env, "Main Office");
let location = String::from_str(&env, "New York");
let admin = Address::generate(&env);

client.create_branch(&branch_id, &name, &location, &admin);

Link Asset to Branch

let asset_id = BytesN::from_array(&env, &[2u8; 32]);
client.add_asset_to_branch(&branch_id, &asset_id);

Retrieve Branch Assets

let assets = client.get_branch_assets(&branch_id);
// Returns Vec<BytesN<32>> of asset IDs

✅ Acceptance Criteria

• Branches can be created and stored on the Stellar ledger
• Assets can be linked to branches and retrieved
• Only the admin can create branches
• Tests pass for all functions
• Module compiles and integrates with errors.rs

[vercel]

@gelluisaac is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[truthixify]

@gelluisaac fix failing CI

[gelluisaac]

@truthixify done

[truthixify]

@gelluisaac

mention the issue it closes in the description

[gelluisaac]

@truthixify done