feat: implement on-chain audit trail module for asset lifecycle tracking

[Hallab7]

Implemented comprehensive audit trail system that records all significant
events for each asset on-chain, providing complete transparency and
traceability for asset lifecycle management.

Changes

Core Implementation

• Added AuditEntry struct with timestamp, action, actor, and details fields
• Implemented append_audit_log() internal function for recording events
• Implemented get_asset_log() public function for retrieving audit history
• Added helper function asset_id_to_bytes() for u64 to BytesN<32> conversion

Module Integration

Asset Module (src/lib.rs):

• register_asset: Records "ASSET_REGISTERED" event
• update_asset_metadata: Records "METADATA_UPDATED" event
• transfer_asset_ownership: Records "OWNERSHIP_TRANSFERRED" event
• retire_asset: Records "ASSET_RETIRED" event

Tokenization Module (src/tokenization.rs):

• tokenize_asset: Records "ASSET_TOKENIZED" event
• mint_tokens: Records "TOKENS_MINTED" event
• burn_tokens: Records "TOKENS_BURNED" event
• transfer_tokens: Records "TOKENS_TRANSFERRED" event

Insurance Module (src/insurance.rs):

• create_policy: Records "INSURANCE_POLICY_CREATED" event
• cancel_policy: Records "INSURANCE_POLICY_CANCELLED" event
• renew_policy: Records "INSURANCE_POLICY_RENEWED" event

Security

• append_audit_log() marked as pub(crate) - only callable internally
• Audit entries are immutable once written
• Public read access via get_asset_audit_logs() contract method
• Chronological ordering guaranteed by append-only design

Testing

• Added 6 comprehensive audit trail tests
• All tests verify chronological ordering and data integrity
• Tests confirm internal function visibility enforcement
• Zero regressions: 194/194 total tests passing

How to Test

Run Audit Trail Tests Only

cargo test --manifest-path AssetsUp/contracts/assetsup/Cargo.toml audit_trail

Expected output:

running 6 tests
test tests::audit_trail::test_audit_log_internal_function_not_directly_callable ... ok
test tests::audit_trail::test_empty_audit_log_for_nonexistent_asset ... ok
test tests::audit_trail::test_audit_log_on_asset_registration ... ok
test tests::audit_trail::test_audit_log_on_asset_retirement ... ok
test tests::audit_trail::test_audit_log_on_ownership_transfer ... ok
test tests::audit_trail::test_audit_log_chronological_order ... ok

test result: ok. 6 passed; 0 failed

Run Full Test Suite

cargo test --manifest-path AssetsUp/contracts/assetsup/Cargo.toml

Expected: 194 tests passing with no failures

Manual Testing Example

// 1. Register an asset
client.register_asset(&asset, &registrar);

// 2. Perform operations
client.update_asset_metadata(&asset_id, &description, &None, &None, &owner);
client.transfer_asset_ownership(&asset_id, &new_owner, &owner);

// 3. Retrieve audit log
let logs = client.get_asset_audit_logs(&asset_id);

// 4. Verify entries
assert_eq!(logs.len(), 3); // registration + update + transfer
let first = logs.get(0).unwrap();
assert_eq!(first.action, String::from_str(&env, "ASSET_REGISTERED"));

Verify Security

Attempting to call append_audit_log from external code will fail at
compile time due to pub(crate) visibility:

// This will NOT compile:
audit::append_audit_log(&env, &asset_id, action, actor, details);
// Error: function `append_audit_log` is private

Breaking Changes

None - This is a new feature with no impact on existing functionality.

Performance Considerations

• Audit logs stored in persistent storage
• Append-only operations are O(1) for writes
• Retrieval is O(n) where n = number of audit entries
• Consider pagination for assets with extensive histories (future enhancement)

Closes #477

[vercel]

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

A member of the Team first needs to authorize it.