Status: Draft
Type: Standards Track
Category: Core
Created: 2025-11-14
Updated: 2026-11-17
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.
Background
Wallets, DEXs, and applications need a common interface for token operations.Goal
CIP-20 defines Cowboy’s native fungible token standard. The runtime manages tokens and supports pause, blacklist, and compliance controls through optional validation hooks.Abstract
The runtime provides the following behavior:- The runtime manages platform tokens.
- An optional validation actor can block transfers for pause, blacklist, or KYC checks.
- Hooks cannot change amounts. The platform does not support fee-on-transfer tokens.
- Platform tokens are 50-100x cheaper than actor-based tokens.
Motivation
Why Platform-Native?
Actor tokens, such as Ethereum’s ERC-20 tokens, have the following costs:
Solana’s SPL Token program demonstrates that platform-native tokens achieve 50-100x better performance.
Why Validation Hooks?
Institutional tokens (stablecoins, securities, RWAs) require compliance controls:- Pause halts all transfers during security incidents.
- A blacklist blocks sanctioned addresses for OFAC compliance.
- KYC restricts transfers to verified addresses.
- Freezing locks individual accounts.
Specification
Token Data Structures
TokenMint
Each token type has a mint record stored in the runtime:TokenAccount
Each holder has a token account per token:Validation Hook Interface
Tokens MAY specify atransfer_hook, an actor that validates transfers through this interface:
Hook Constraints
- Hooks cannot modify amounts.
- Hooks cannot add transfers or implement fee-on-transfer behavior.
- The runtime caps hook calls at 50,000 Cycles and 50,000 Cells. For the pre-hook
can_transfer, exceeding the cap fails (reverts) the transfer. For the post-hookon_transfer, exceeding the cap is treated like any other post-hook failure: logged and ignored, and the transfer is NOT reverted. - If
can_transferreturns False, the transfer reverts. - Hooks cannot trigger transfers of the same token.
Example: USDC Compliance Hook
Host Functions
System Opcode Assignments
Each token System instruction has a fixed opcode (allocated incowboy-protocol-codec and pinned by the opcode-uniqueness test):
Opcodes 21–23 (allowance-delta ops + permit) exist in code but were previously undocumented in this CIP.
The Cowboy runtime exposes these native functions for token operations:
Token Creation
Transfers
Approvals
Queries
Minting and Burning
Administration
token_set_mint_authority and token_set_freeze_authority are top-level
System instructions. Both authorize the transaction signer (tx.from) against
the current authority holder. There is no PVM host call for freezing,
unfreezing or setting an authority. token_set_hook and
token_transfer_ownership are also System-only, with no PVM host function.
An actor that creates a platform token holds all three roles at its actor
address. It cannot change the owner role or hook. A mint or freeze authority
held by an actor, whether from creation or handover, cannot yet be moved or
renounced. An actor-held freeze authority cannot freeze or unfreeze accounts.
An actor-held mint authority can still mint through the token_mint host
call. Support for these actor administration operations requires a future
protocol change.
TOKEN_AUTHORITY_TRANSFER_ACTIVATION_HEIGHT is scheduled and reached —
it is dormant on every network today — both instructions are refused at
admission, in proposals and in blocks, and no token’s mint or freeze authority
can change. See CIP-50 for gate semantics.
Events
Platform tokens emit standardized events:None is encoded as the zero address in the authority and hook events.
Storage Layout
Platform tokens are stored in a dedicated runtime state section:Actor Token Interface
For tokens requiring custom transfer logic (fee-on-transfer, rebasing, complex vesting), implement as an actor. Actor tokens SHOULD implement this interface for ecosystem compatibility:Transfer and Approval events matching the platform token format.
When to Use Actor Tokens
SDK Usage
The Cowboy SDK wraps the host functions:Security Considerations
Approval Race Condition
Theapprove function has a known race condition (inherited from ERC-20). If Alice approves Bob for 100, then changes to 50, Bob can front-run and spend 100 + 50.
The SDK should use increase_allowance / decrease_allowance patterns to mitigate this race. This CIP does not specify them.
Hook Security
- The runtime caps hooks at 50,000 Cycles and 50,000 Cells to prevent DoS.
- Hooks cannot trigger transfers of the same token.
- Hooks MUST be deterministic. Non-deterministic hooks break consensus.
- Changing the hook address affects all future transfers. For critical tokens, hold the owner role in a CIP-49 threshold (multi-signer) account; an actor such as an on-chain timelock cannot change the hook as owner until a future protocol change.
Mint and Freeze Authority
The creator starts as owner, mint authority and freeze authority. Transferring ownership moves only the owner role, so a buyer of a token has not taken control until the creator has also handed over or renounced the mint and freeze authorities. Each authority is moved or renounced by its current holder withtoken_set_mint_authority / token_set_freeze_authority. Renouncing the mint
authority ends minting for good; renouncing the freeze authority ends freezing
and unfreezing for good.
Renouncing the freeze authority does not unfreeze any accounts. Accounts
frozen at that moment stay frozen permanently; unfreeze them first.
If a mint or freeze key leaks, its holder can rotate the authority to a fresh
signer with token_set_mint_authority or token_set_freeze_authority.
Anyone holding the same key can make the same call. Rotation is a race: the
first included transaction wins, and the attacker may take or renounce the
authority instead. Transferring ownership alone does not retire a leaked key.
An owner that does not hold an authority cannot rotate it.
The owner’s transfer hook can still block transfers. A buyer checking for
decentralization should check owner and the hook as well as the two
authorities.
For decentralized tokens, consider:
- Renouncing the mint authority once supply is final, so no key can dilute holders
- Renouncing the freeze authority (no freezing or unfreezing), or holding it in a CIP-49 threshold (multi-signer) account
Integer Handling
Python integers have arbitrary precision, preventing overflow. However:- Implementations MUST check
balance >= amountbefore transfers - Implementations MUST check
allowance >= amountbefore transferFrom - Implementations MUST check
total_supply + amount <= max_supplybefore minting - Independent of the per-token
max_supply,total_supplyis hard-capped at the protocol constantMAX_TOKEN_SUPPLY = 1e30 wei; create and mint reject any supply that would exceed it, so “None = unlimited” means “bounded only by the protocol cap”
Rationale
Why Not Dual-Mode?
Two parallel CIP-20 token standards, one for platform tokens and one for actor tokens, would require:- Every tool to support both types.
- Developers to choose a mode.
- Protocols to handle interactions between token types.
Why Validation-Only Hooks?
Hooks that can modify transfer amounts (like Uniswap V4) add complexity:- Unpredictable final amounts
- Complex gas estimation
- Potential for hidden fees
- The transfer succeeds or fails.
- Gas is predictable (hook cost is bounded)
- Covers institutional requirements (pause, blacklist, KYC)
Why Not EVM Compatibility?
Cowboy is a Python-first chain. ERC-20 compatibility would require running EVM bytecode. CIP-20 provides:- Familiar method names for Ethereum developers
- Similar mental model (balances, allowances, events)
- Canonical bridge for wrapping Cowboy tokens as ERC-20s on Ethereum (separate CIP)