Skip to main content
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.
As of 2026-03-27, the implementation uses u128 token amounts. The original specification used u256. u128 supports up to ~3.4 × 10³⁸, sufficient for token economies with 18 decimal places. u128 executes in two native CPU instructions; u256 requires software emulation.
CBY is the protocol-layer native currency and is NOT a CIP-20 token. CIP-20 manages user-created fungible tokens.

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.
Implement tokens that require custom transfer logic, such as fee-on-transfer or rebasing, as actors using the CIP-20 actor interface.

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.
A validation hook can block a transfer. It cannot modify amounts.

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:
Allowances are stored separately:

Validation Hook Interface

Tokens MAY specify a transfer_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-hook on_transfer, exceeding the cap is treated like any other post-hook failure: logged and ignored, and the transfer is NOT reverted.
  • If can_transfer returns 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 in cowboy-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.
Until 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:
Actor tokens MUST emit 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

The approve 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 with token_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 >= amount before transfers
  • Implementations MUST check allowance >= amount before transferFrom
  • Implementations MUST check total_supply + amount <= max_supply before minting
  • Independent of the per-token max_supply, total_supply is hard-capped at the protocol constant MAX_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:
  1. Every tool to support both types.
  2. Developers to choose a mode.
  3. Protocols to handle interactions between token types.
The platform token standard covers 95%+ of use cases. Actor tokens support custom logic.

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
Validation-only hooks are simpler:
  • The transfer succeeds or fails.
  • Gas is predictable (hook cost is bounded)
  • Covers institutional requirements (pause, blacklist, KYC)
Tokens needing amount modification (fee-on-transfer) use actor tokens.

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)

Backwards Compatibility

This new standard has no backwards compatibility requirements.