Skip to main content

Overview

This is a Security Token smart contract implementation from CoMakery (dba Upside). The core purpose of the token is to enforce transfer restrictions for certain groups while supporting multiple token types (RegS, RegD, RegCF, etc.) based on investor identity and regulatory requirements.

This implementation attempts to balance simplicity and sufficiency for smart contract security tokens that need to comply with regulatory authorities - without adding unnecessary complexity for simple use cases. It implements the ERC-20 token standard with ERC-1404 security token transfer restrictions, enhanced with multi-type token functionality.

This approach takes into account yet to be standardized guidance from ERC-1400 (which has additional recommendations for more complex security token needs) and ERC-1404 which offers an approach similar to ERC-902. Unfortunately ERC-1404 does not adopt ERC-1066 standard error codes - which this project may adopt in the future. Since no security token standards have reached mass adoption or maturity and they do not fully agree with each other, the token optimizes for a simple and sufficient implementation.

Simplicity is desirable so that contract functionality is clear. It also reduces the number of smart contract lines that need to be secured (each line of a smart contract is a security liability).

Documentation​

For detailed guides and subsystem documentation, see:

Architecture Overview​

The system uses a fallback extension pattern for the main RestrictedLockupToken contract to keep core functionality manageable while supporting advanced features through the RestrictedLockupTokenExtension contract. This pattern provides:

  • Modular Design: Core token functionality remains focused while advanced features are delegated
  • Gas Optimization: Complex operations are handled by specialized contracts with optimized storage patterns
  • Maintainability: Changes to advanced features don't require redeployment of the core token
  • Shared Storage: Both contracts operate on the same storage layout ensuring data consistency

RestrictedLockupTokenExtension​

The RestrictedLockupTokenExtension contract handles advanced token holder management and optimized token holding operations through a delegatecall fallback pattern. Key responsibilities include:

  • Holding Management: Efficient querying and manipulation of token holdings using bitmask optimization
  • Access Control: Extended admin role validation and permission checking
  • Gas-Optimized Operations: Advanced algorithms for token type management and balance calculations

The extension pattern ensures that:

  1. Identical Storage Layout: Both contracts share the exact same storage structure through the Storage base contract
  2. Seamless Integration: Function calls are transparently delegated from the main contract
  3. Backwards Compatibility: Standard ERC-20 operations remain unaffected

Disclaimer​

This open or closed source software is provided with no warranty. This is not legal advice. CoMakery (dba Upside) is not a legal firm and is not your lawyer. Securities are highly regulated across multiple jurisdictions. Issuing a security token incorrectly can result in financial penalties or jail time if done incorrectly. Consult a lawyer and tax advisor. Conduct an independent security audit of the code.

System Architecture Summary

This security token system represents a comprehensive solution for regulatory-compliant digital assets with advanced features for modern DeFi and TradFi integration.

Core Innovations​

1. Fallback Extension Pattern​

  • Modular Architecture: Core token functionality separated from advanced features via RestrictedLockupTokenExtension
  • Shared Storage: Both contracts operate on identical storage layout through delegatecall
  • Gas Optimization: Complex operations delegated to specialized contract with optimized algorithms
  • Maintainability: Advanced features can be updated without redeploying core token

2. Bitmask-Optimized Holdings​

  • Efficient Storage: Holdings tracked using bitmap indices instead of arrays
  • Popcount Operations: Fast counting of holdings using CPU-level bit manipulation
  • BitScan Algorithms: Direct access to specific holdings without iteration
  • Gas Savings: Significant reduction in gas costs for users with many holdings

3. Multi-Type Token System​

  • Regulatory Compliance: Single contract handles RegS, RegD, RegCF, and custom token types
  • Automatic Classification: Token types assigned based on investor identity and rules
  • FIFO Transfer Logic: Maintains regulatory compliance through oldest-first transfers
  • Flexible Minting: Both automatic and explicit token type specification

4. Unified Interest & Dividends Contract​

  • Dual Functionality: Handles both debt-like interest payments and equity-like dividends
  • Snapshot Integration: Leverages SnapshotPeriods for historical balance calculations
  • Multiple Token Support: Distribute any ERC-20 token as dividends or interest
  • Backward Compatibility: Maintains IDividends interface for existing integrations

5. Atomic Purchase System​

  • Multi-Party Payments: Single transaction handles originator, admin, and interest funding
  • AML/KYC Integration: Automatic compliance validation for all participants
  • Purchase Tracking: Unique identifiers prevent duplicate transactions
  • Automation Ready: Designed for external system integration

Administrative Role System​

The system implements a granular 6-role access control system:

RoleBitPrimary Functions
Contract Admin1System configuration, emergency controls
Reserve Admin2Token supply management, direct burns
Wallets Admin4Address compliance, group management
Transfer Admin8Transfer rules, payment operations
Soft Burn Admin16Allowance-based burning for DeFi
Mint Admin32Specialized minting operations

This design enables precise responsibility delegation while maintaining security boundaries.

Advanced Operations​

Burning Mechanisms​

  • Standard Burn: Reserve Admin direct authority
  • Soft Burn: Allowance-based for DeFi protocols
  • Specific Holding Burn: Precise targeting by global index

Holding Management​

  • Wallet Holdings: User-specific view with FIFO ordering
  • Global Holdings: System-wide administrative view
  • Transfer Operations: Standard FIFO, timelock, and specific holding transfers
  • Token Type Updates: Regulatory reclassification support

Snapshot System​

  • Time-Weighted Ownership: Fair interest/dividend calculations
  • Historical Lookups: Past balance queries for any timestamp
  • Automatic Updates: Seamless integration with token transfers

Integration Capabilities​

DeFi Integration​

  • Soft Burn: Allowance-based burning for yield farming
  • ERC-20 Compatibility: Standard interface maintained
  • Batch Operations: Gas-efficient multi-transaction support

TradFi Integration​

  • Purchase Contract: Atomic USDC-to-token exchanges
  • Interest Payments: Bond-like interest accrual and claiming
  • Dividend Distributions: Equity-like profit sharing

Compliance Features​

  • AML/KYC: Integrated identity verification
  • Transfer Restrictions: Regulatory holding periods
  • Audit Trails: Complete transaction and holding history
  • Role Separation: Multi-signature governance support

Performance Optimizations​

Gas Efficiency​

  • Bitmask Storage: Compact holding representation
  • Batch Updates: Multiple operations in single transaction
  • Direct Index Access: No array iteration required
  • Optimized Algorithms: CPU-level bit operations

Scalability​

  • Delegated Architecture: Complex operations in extension contract
  • Efficient Queries: Fast holding lookups and counts
  • Minimal Storage: Optimal use of blockchain storage

This architecture provides a robust foundation for enterprise-grade security tokens while maintaining the flexibility needed for diverse regulatory environments and use cases. The system balances regulatory compliance, gas efficiency, and operational flexibility to support both traditional finance integration and modern DeFi protocols.