OP_20 Standard

The OP_20 standard provides a unified specification for fungible tokens within the OP_NET ecosystem. This reference is intended for developers who need to implement compliant tokens or integrate OP_20 functionality into their applications.

IOP20 Interface

The IOP20 interface specifies all methods and properties that an OP_20 token must implement:

assemblyscript

IOP20 Interface

interface IOP20 {
    name(): string;
    symbol(): string;
    icon(): string;
    decimals(): u8;
    totalSupply(): u256;
    metadata():
        {name: string, symbol: string, icon: string, decimals: u8, totalSupply: u256, domainSeparator: u8[32]};
    domainSeparator(): u8[32];
    balanceOf(owner: Address): u256;
    nonceOf(owner: Address): u256;
    allowance(owner: Address, spender: Address): u256;
    safeTransfer(to: Address, amount: u256, data?: u8[]): void;
    safeTransferFrom(from: Address, to: Address, amount: u256, data?: u8[]): void;
    transfer(to: Address, amount: u256): void;
    transferFrom(from: Address, to: Address, amount: u256): void;
    burn(amount: u256): void;
    increaseAllowance(spender: Address, amount: u256): void;
    decreaseAllowance(spender: Address, amount: u256): void;
    increaseAllowanceBySignature(owner: Address, spender: Address, amount: u256,
        deadline: u64, signature: u8[]): void;
    decreaseAllowanceBySignature(owner: Address, spender: Address, amount: u256,
        deadline: u64, signature: u8[]): void;
}

Methods and Properties

name

Signature

name(): string

Description

Returns the token name.

Returns

Name	Type	Description
name	string	Token name.

symbol

Signature

symbol(): string

Description

Returns the token symbol.

Returns

Name	Type	Description
symbol	string	Token symbol.

icon

Signature

icon(): string

Description

Returns the token's icon URL (http(s) or ipfs) or identifier for wallet/UI display.

Returns

Name	Type	Description
icon	string	Icon URL.

decimals

Signature

decimals(): u8

Description

Returns the number of decimal places used by the token. Valid range: 0-32. A value of 0 creates indivisible tokens.

Returns

Name	Type	Description
decimals	u8	Number of decimals.

totalSupply

Signature

totalSupply(): u256

Description

Returns the current circulating amount of tokens.

Returns

Name	Type	Description
totalSupply	u256	Current total supply.

metadata

Signature

metadata():
{
    name: string,
    symbol:string,
    icon: string,
    decimals: u8,
    totalSupply: u256,
    domainSeparator: u8[32]
}

Description

Returns all token metadata in a single call.

Returns

Name	Type	Description
name	string	Token name.
symbol	string	Token symbol.
icon	string	Icon URL.
decimals	u8	Number of decimals.
totalSupply	u256	Current total supply.
domainSeparator	u8[32]	32-byte domain separator hash.

domainSeparator

Signature

domainSeparator(): u8[32]

Description

Returns a SHA-256 hash representing the unique domain separator. The hash must be derived from the OP712Domain structure.

Returns

Name	Type	Description
domainSeparator	u8[32]	32-byte domain separator hash.

balanceOf

Signature

balanceOf(owner: Address): u256

Description

Returns the actual token balance for an address. Non-existent addresses must return 0.

Parameters

Name	Type	Required	Description
owner	Address	-

Returns

Name	Type	Description
balance	u256	Balance.

nonceOf

Signature

nonceOf(owner: Address): u256

Description

Returns the current nonce for an address. Non-existent addresses must return 0.

Parameters

Name	Type	Required	Description
owner	Address	-

Returns

Name	Type	Description
nonce	u256	Current nonce.

allowance

Signature

allowance(owner: Address, spender: Address): u256

Description

Returns the spender's remaining allowance from the owner's account. Non-existent addresses must return 0.

Parameters

Name	Type	Required	Description
owner	Address	-
spender	Address	-

Returns

Name	Type	Description
remaining	u256	Remaining allowance.

safeTransfer

Signature

safeTransfer(to: Address, amount: u256, data?: u8[]): void

Description

Transfers amount of tokens to the "to" address with delivery confirmation for contract recipients.

The method must revert if:

The sender have insufficient balance.
The to is the zero address or the dead address.
A failed acknowledgments is received.

Parameters

Name	Type	Required	Description
to	Address	-
amount	u256	-
data?	u8[]	-	Optional data.

Events

Type	Description
Transferred	Must emit a Transferred event.

safeTransferFrom

Signature

safeTransferFrom(from: Address, to: Address, amount: u256, data?: u8[]): void

Description

Transfers amount of tokens from the "from" address to the "to" address with delivery confirmation for contract recipients.

The method must revert if:

Spends allowance is too low or not set (unless sender equals from).
The sender have insufficient balance.
The to is the zero address or the dead address.
A failed acknowledgments is received.

The method must handle infinite allowance (u256.Max) without decrementing

Parameters

Name	Type	Required	Description
from	Address	-
to	Address	-
amount	u256	-
data?	u8[]	-	Optional data.

Events

Type	Description
Transferred	Must emit a Transferred event.

transfer

Signature

transfer(to: Address, amount: u256): void

Description

Transfers amount of tokens to the "to" address.

The method must revert if:

The sender have insufficient balance.
The to is the zero address or the dead address.

Parameters

Name	Type	Required	Description
to	Address	-
amount	u256	-

Events

Type	Description
Transferred	Must emit a Transferred event.

transferFrom

Signature

transferFrom(from: Address, to: Address, amount: u256): void

Description

Transfers amount of tokens from the "from" address to the "to" address.

The method must revert if:

Spends allowance is too low or not set (unless sender equals from).
The sender have insufficient balance.
The to is the zero address or the dead address.

The method must handle infinite allowance (u256.Max) without decrementing.

Parameters

Name	Type	Required
from	Address	-
to	Address	-
amount	u256	-

Events

Type	Description
Transferred	Must emit a Transferred event.

burn

Signature

burn(amount: u256): void

Description

Atomically subtract amount from the caller’s balance and reduce totalSupply by the same amount.

The method must revert if:

The caller is the zero address or the dead address.
The amount is smaller then the caller balance.

Parameters

Name	Type	Required	Description
amount	u256	-

Events

Type	Description
Burned	Must emit a Burned event.

increaseAllowance

Signature

increaseAllowance(spender: Address, amount:u256): void

Description

Atomically increase spender allowance permission on the owner's account for the specified amount.

The method must revert if:

The spender addresss is the zero address or the dead address.

Requirements:

The method must handle overflow by setting allowance to u256.Max.

Parameters

Name	Type	Required	Description
spender	Address	-
amount	u256	-

Events

Type	Description
Approved	Must emit an Approved event.

decreaseAllowance

Signature

decreaseAllowance(spender: Address, amount: u256): void

Description

Atomically decrease spender allowance permission on the owner's account for the specified amount.

The method must revert if:

The spender addresss is the zero address or the dead address.

Requirements:

The method must handle undeflow by setting the allowance to 0.

Parameters

Name	Type	Required	Description
spender	Address	-
amount	u256	-

Events

Type	Description
Approved	Must emit an Approved event.

increaseAllowanceBySignature

Signature

increaseAllowanceBySignature(owner: Address, spender: Address, amount: u256, deadline: u64, signature: u8[]): void

Description

Atomically increase spender allowance off-chain on the owner's account for the specified amount.

The method must revert if:

The spender addresss is the zero address or the dead address.
The signature verification fail.

Requirements:

The message must be signed in accordance with the OP20AllowanceIncrease structure.
The method must handle overflow by setting allowance to u256.Max.

Parameters

Name	Type	Required
owner	Address	-
spender	Address	-
amount	u256	-
deadline	u64	-
signature	u8[]	-

Events

Type	Description
Approved	Must emit an Approved event.

decreaseAllowanceBySignature

Signature

decreaseAllowanceBySignature(owner: Address, spender: Address, amount: u256, deadline: u64, signature: u8[]): void

Description

Atomically decrease spender allowance off-chain on the owner's account for the specified amount.

The method must revert if:

The spender addresss is the zero address or the dead address.
The signature verification fail.

Requirements:

The message must be signed in accordance with the OP20AllowanceDecrease structure.
The method must handle underflow by setting allowance to 0.

Parameters

Name	Type	Required
owner	Address	-
spender	Address	-
amount	u256	-
deadline	u64	-
signature	u8[]	-

Events

Type	Description
Approved	Must emit an Approved event.

Events

The OP_20 standard defines three events: Approved, Burned, and Transferred. These are already implemented by the OP20ApprovedEvent, OP20BurnedEvent, and OP20TransferredEvent classes respectively:

Approved

assemblyscript

OP20ApprovedEvent

class OP20ApprovedEvent extends NetEvent
    constructor(owner: Address, spender: Address, amount: u256);
}

Reference

constructor

Signature

constructor(owner: Address, spender: Address, amount: u256)

Description

An Approved event is emitted when allowance is modified through any method.

Parameters

Name	Type	Required	Description
owner	Address	-	Token owner.
spender	Address	-	Authorized spender.
amount	u256	-	New total allowance (not delta).

Burned

assemblyscript

OP20BurnedEvent

class OP20BurnedEvent extends NetEvent {
    constructor(from: Address, amount: u256);
}

Reference

constructor

Signature

constructor(from: Address, amount: u256)

Description

A Burned event is emitted when tokens are permanently removed from circulation.

Parameters

Name	Type	Required	Description
from	Address	-	Address losing tokens.
amount	u256	-	Number of tokens destroyed.

Transferred

assemblyscript

OP20TransferredEvent

class OP20TransferredEvent extends NetEvent {
    constructor(operator: Address, from: Address, to: Address, amount: u256);
}

Reference

constructor

Signature

constructor(operator: Address, from: Address, to: Address, amount: u256)

Description

A Transferred event is emitted on all successful transfers.

Parameters

Name	Type	Required	Description
operator	Address	-	Who initiated the transfer.
from	Address	-	Source of tokens.
to	Address	-	Destination of tokens.
amount	u256	-	Number of tokens transferred.

Callbacks

The OP_20 standard currently includes one callback, defined by the IOP20Receiver interface:

assemblyscript

Callbacks

interface IOP20Receiver {
    onOP20Received(operator: Address, from: Address, amount: u256, data: u8[]): u32;
}

Reference

onOP20Received

Signature

onOP20Received(operator: Address, from: Address, amount: u256, data: u8[]): u32

Description

Smart contracts accepting OP_20 tokens must implement this method to provide delivery confirmation to the safe transfer operations. A return value other than ON_OP20_RECEIVED_SELECTOR or a revert must causes transfer to fail.

Parameters

Name	Type	Required	Description
operator	Address	-	Who initiated the transfer.
from	Address	-	Original token owner.
amount	u256	-	Number of tokens received.
data	u8[]	-	Additional data.

Returns

Name	Type	Description
value	u32	To accept the transfer, return value must be ON_OP20_RECEIVED_SELECTOR (0xd83e7dbc). To reject it, return any other values.

Data Structures

OP712Domain

assemblyscript

OP712Domain

OP712Domain(
    domainType: u8[32],
    nameHash: u8[32],
    versionHash: u8[32],
    chainId: u8[32],
    protocolId u8[32] ,
    verifyingContract: Address
);

Reference

OP712Domain

Signature

OP712Domain

Description

domainSeparator 32-bytes hash structure.

Parameters

Name	Type	Required	Description
domainType	u8[32]	-	sha256('OP712Domain(string name,string version,bytes32 chainId,bytes32 protocolId,address verifyingContract)')
nameHash	u8[32]	-	sha256 of the token name.
versionHash	u8[]	-	sha256('1')
chainId	u8[32]	-	OP_NET chain identifier.
protocolId	u8[32]	-	OP_NET protocol identifier.
verifyingContract	Address	-	Token contract address.

OP20AllowanceIncrease

assemblyscript

OP20AllowanceIncrease


OP20AllowanceIncrease(
    typeHash: u8[32],
    owner: Address,
    spender: Address,
    amount: u256,
    nonce: u256,
    deadline: u64
);

Reference

OP20AllowanceIncrease

Signature

OP20AllowanceIncrease

Description

increaseAllowanceBySignature 64-bytes signature structure.

Parameters

Name	Type	Required	Description
typeHash	u8[]	-	sha256('OP20AllowanceIncrease(address owner,address spender,uint256 amount,uint256 nonce,uint64 deadline)')
owner	Address	-
spender	Address	-
amount	u256	-
nonce	u256	-
deadline	u64	-

OP20AllowanceDecrease

assemblyscript

OP20AllowanceDecrease


OP20AllowanceDecrease(
    typeHash: u8[32],
    owner: Address,
    spender: Address,
    amount: u256,
    nonce: u256,
    deadline: u64
);

Reference

OP20AllowanceDecrease

Signature

OP20AllowanceDecrease

Description

decreaseAllowanceBySignature 64-bytes signature structure.

Parameters

Name	Type	Required	Description
typeHash	u8[]	-	sha256('OP20AllowanceDecrease(address owner,address spender,uint256 amount,uint256 nonce,uint64 deadline)')
owner	Address	-
spender	Address	-
amount	u256	-
nonce	u256	-
deadline	u64	-	Expiration block.