Implement Multi-Sig Admin, Token Clawback, Token Locking, and SDK Eve…

[Ceejaytech25]

PR Summary: Enhanced Security, Regulatory Compliance, and SDK Event Streaming

This PR implements four major architectural upgrades across the bc-forge contracts and TypeScript SDK, focusing on multi-signature governance, regulatory clawback capabilities, time-bound token locking, and robust event parsing.

🚀 Key Implementations

1. Multi-Signature Admin Constraints (#26)

Revamped the singular admin model to support M-of-N collective approvals.

• Admin Pool & Threshold: Introduced an internal pool of administrators with a configurable quorum threshold.
• Proposal Workflow: Added a native proposal system (create_proposal, approve_proposal, execute_proposal) allowing admins to stage sensitive operations (Mint, Pause, Unpause) for collective verification before execution.
• Natively Integrated: Updated the token contract to leverage these multi-sig primitives for high-risk configuration events.

2. Token Clawback Functionality (SEP-0008) (#23)

Implemented an authority layer capable of recovering assets in compliance with regulatory requirements.

• ClawbackAdmin: Added a specific role delegated solely for asset recovery, isolated from standard user protections.
• Restricted Execution: The clawback(from, to, amount) function allows for secure balance adjustments by the Clawback authority.
• Full Traceability: Integrated specific clawback events for transparent audit trails.

3. Token Locking & Time Constraints (#29)

Introduced a native protocol for vesting and delayed deployment schedules.

• Lockup Timeline: Funds can be locked for specific users until a target ledger timestamp is reached.
• Chronological Verification: Securely tracks ledger time outputs to prevent premature withdrawals or dumps.
• Graceful Release: Users can call withdraw_locked only after the release interval has passed authentically.

4. SDK Event Parsing & Real-Time Subscriptions (#21)

Heavy industrialization of the TypeScript SDK to support modern data-streaming requirements.

• Event Typings: New sdk/src/events.ts with comprehensive type classifications for all contract broadcasts.
• XDR Decoders: Robust handlers to translate raw diagnostic events and RPC outputs into developer-friendly native variants.
• Subscription Support: Added subscribeEvents logic providing clean, callback-based real-time streams with memory-safe polling.

🛠 Technical Details

• Contracts: Updated contracts/admin, contracts/token, and events.rs.
• SDK: Updated client.ts, index.ts, and added events.ts.
• Standards: Compliant with SEP-0041 (Token) and SEP-0008 (Clawback).
• Security: Intensive architectural updates scaling internal cryptographic security procedures structurally.

✅ Acceptance Criteria Verified

• Admin Pool constructing alongside minimum quorum values.
• Functional proposal operations for token-modifiers.
• Restricted ClawbackAdmin designation overriding general protections.
• Ledger-time based withdrawal gates for locked funds.
• Broad translation typings modeling Soroban events natively in SDK.
• Real-time event subscription handlers implemented.

---

This PR completes the security and SDK roadmap for the current milestone.

Closes #26
Closes #23
Closes #29
Closes #21

[drips-wave]

@Ceejaytech25 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Ceejaytech25]

@p3ris0n , pls review PR

[p3ris0n]

@Ceejaytech25 please resolve conflicts