CIP-20: Fungible Token Standard

from cowboy_sdk import PlatformToken

# Create a new platform-level token
usdc_id = PlatformToken.create(
    name="USD Coin",
    symbol="USDC",
    decimals=6,
    initial_supply=1_000_000 * 10**6,
    max_supply=None  # Optional supply cap
)

# Transfer (very cheap - ~1,000 Cycles)
PlatformToken.transfer(token_id=usdc_id, to=recipient, amount=1000)

# Batch transfer (even more efficient)
PlatformToken.transfer_batch([
    (usdc_id, alice, 100),
    (weth_id, bob, 50),
    (dai_id, charlie, 200)
])

# Check balance
balance = PlatformToken.balance_of(token_id=usdc_id, owner=address)

# Approve spender
PlatformToken.approve(token_id=usdc_id, spender=dex_address, amount=1000)

# Transfer from (using allowance)
PlatformToken.transfer_from(
    token_id=usdc_id,
    from_address=user,
    to=recipient,
    amount=500
)

# Mint (only mint_authority)
PlatformToken.mint(token_id=usdc_id, to=user, amount=1000)

# Burn
PlatformToken.burn(token_id=usdc_id, amount=500)

# Emitted automatically by runtime
TokenTransfer(token_id: bytes32, from: address, to: address, amount: u256)
TokenApproval(token_id: bytes32, owner: address, spender: address, amount: u256)
TokenMint(token_id: bytes32, to: address, amount: u256)
TokenBurn(token_id: bytes32, from: address, amount: u256)

class CIP20Token:
    """
    A conceptual interface for a CIP-20 compliant token actor.
    Actual implementation will use the Cowboy SDK and actor model.
    """

    def name(self) -> str:
        """
        Returns the name of the token (e.g., "MyToken").
        This method is optional.
        """
        pass

    def symbol(self) -> str:
        """
        Returns the symbol of the token (e.g., "MTK").
        This method is optional.
        """
        pass

    def decimals(self) -> int:
        """
        Returns the number of decimals the token uses.
        e.g., 18 for many tokens, which means that a balance of 10^18 represents 1 token.
        This method is optional.
        """
        pass

    def total_supply(self) -> int:
        """
        Returns the total token supply.
        """
        pass

    def balance_of(self, owner: address) -> int:
        """
        Returns the account balance of another account with address `owner`.
        """
        pass

    def transfer(self, to: address, amount: int) -> bool:
        """
        Transfers `amount` tokens from the message sender's account to the `to` address.
        MUST emit a `Transfer` event.
        MUST return `True` on success.
        """
        pass

    def approve(self, spender: address, amount: int) -> bool:
        """
        Allows `spender` to withdraw from the message sender's account multiple times, up to the `amount`.
        If this function is called again, it overwrites the current allowance with `amount`.
        MUST emit an `Approval` event.
        MUST return `True` on success.
        """
        pass

    def allowance(self, owner: address, spender: address) -> int:
        """
        Returns the amount which `spender` is still allowed to withdraw from `owner`.
        """
        pass

    def transfer_from(self, from_address: address, to: address, amount: int) -> bool:
        """
        Transfers `amount` tokens from `from_address` to `to` address using the allowance mechanism. The caller of this method must have
        an allowance from `from_address` of at least `amount`.
        MUST emit a `Transfer` event.
        MUST return `True` on success.
        """
        pass

# Event signature
Transfer(from_address: address, to: address, amount: int)

# Event signature
Approval(owner: address, spender: address, amount: int)

@dataclass
class TokenMint:
    """Platform-level token mint definition (stored in runtime state)"""
    token_id: bytes32           # Unique identifier (keccak256(creator || symbol || nonce))
    name: str                   # Token name (e.g., "USD Coin")
    symbol: str                 # Token symbol (e.g., "USDC")
    decimals: u8                # Decimal precision (0-18)
    total_supply: u256          # Current circulating supply
    max_supply: u256 | None     # Optional supply cap
    mint_authority: address     # Who can mint new tokens
    freeze_authority: address | None  # Who can freeze accounts (optional)
    created_at: u64             # Block timestamp of creation
    metadata_uri: str | None    # Optional URI to metadata (logo, etc.)

@dataclass
class TokenAccount:
    """User balance for a specific token (stored in runtime state)"""
    owner: address              # Account owner
    token_id: bytes32           # Which token this account holds
    balance: u256               # Current balance
    allowances: dict[address, u256]  # Approved spenders
    frozen: bool                # Is this account frozen?

def create_token(
    name: str,
    symbol: str,
    decimals: u8,
    initial_supply: u256,
    max_supply: u256 | None = None,
    metadata_uri: str | None = None
) -> bytes32:
    """
    Create a new platform-level token.

    Returns: token_id (bytes32)

    Cost:
      - Cycles: 10,000 (one-time creation cost)
      - Cells: len(name) + len(symbol) + 256 bytes (mint record + metadata)

    The caller becomes the mint_authority and freeze_authority.
    initial_supply is minted to the caller's account.

    Token ID is deterministically generated:
      token_id = keccak256(caller_address || symbol || creation_nonce)
    """

def token_transfer(
    token_id: bytes32,
    to: address,
    amount: u256
) -> bool:
    """
    Transfer tokens from caller to recipient.

    Cost:
      - Cycles: 1,000 (50x cheaper than actor message!)
      - Cells: 64 bytes (2 balance updates)

    Emits: TokenTransfer(token_id, msg.sender, to, amount)

    Returns: True on success
    Reverts if: insufficient balance, account frozen
    """

def token_transfer_batch(
    transfers: list[tuple[bytes32, address, u256]]
) -> bool:
    """
    Transfer multiple tokens in a single transaction.

    Cost:
      - Cycles: 500 + (500 * len(transfers))
      - Cells: 32 * len(transfers)

    Example:
      token_transfer_batch([
          (usdc_id, alice, 100 * 10**6),
          (weth_id, bob, 5 * 10**18),
          (dai_id, charlie, 1000 * 10**18)
      ])

    This is much more efficient than 3 separate transfers:
      - Batch: ~2,000 Cycles
      - Separate: ~3,000 Cycles + 3x transaction overhead

    Returns: True if all transfers succeed
    Reverts if: any transfer fails (atomicity guaranteed)
    """

def token_approve(
    token_id: bytes32,
    spender: address,
    amount: u256
) -> bool:
    """
    Approve spender to transfer up to amount on behalf of caller.

    Cost:
      - Cycles: 500
      - Cells: 32 bytes

    Emits: TokenApproval(token_id, msg.sender, spender, amount)

    Note: Overwrites existing allowance (ERC-20 race condition applies)
    """

def token_transfer_from(
    token_id: bytes32,
    from_address: address,
    to: address,
    amount: u256
) -> bool:
    """
    Transfer tokens using allowance mechanism.

    Requires: caller has allowance from from_address >= amount

    Cost:
      - Cycles: 1,500 (allowance check + transfer)
      - Cells: 96 bytes (allowance update + 2 balance updates)

    Emits: TokenTransfer(token_id, from_address, to, amount)

    Returns: True on success
    Reverts if: insufficient allowance, insufficient balance
    """

def token_balance_of(
    token_id: bytes32,
    owner: address
) -> u256:
    """
    Get token balance for an account.

    Cost:
      - Cycles: 100 (read-only, very cheap)
      - Cells: 0 (no state mutation)

    Returns: Balance (0 if account doesn't exist)
    """

def token_mint(
    token_id: bytes32,
    to: address,
    amount: u256
) -> bool:
    """
    Mint new tokens (only callable by mint_authority).

    Requires: msg.sender == token.mint_authority

    Cost:
      - Cycles: 1,000
      - Cells: 64 bytes (total_supply + recipient balance)

    Emits: TokenMint(token_id, to, amount)

    Returns: True on success
    Reverts if:
      - Caller is not mint_authority
      - Would exceed max_supply (if set)
    """

def token_burn(
    token_id: bytes32,
    amount: u256
) -> bool:
    """
    Burn tokens from caller's balance.

    Cost:
      - Cycles: 500
      - Cells: 64 bytes (total_supply + caller balance)

    Emits: TokenBurn(token_id, msg.sender, amount)

    Returns: True on success
    Reverts if: insufficient balance
    """

Runtime State Tree:
├── accounts/
│   └── {address}/
│       └── balance (CBY native token)
├── actors/
│   └── {actor_address}/
│       └── code, storage, etc.
└── platform_tokens/  ← New section
    ├── mints/
    │   └── {token_id}/
    │       └── TokenMint struct
    └── accounts/
        └── {owner_address}/
            └── {token_id}/
                └── TokenAccount struct