Documentation
Returns the token name.
This is a read-only method.
OP-20 Implementations
Introduction
All OP_NET smart contracts:- Are required to extend the OP_NET base class (directly or indirectly).
- Use the Calldata parameters and BytesWriter return values patterns.
- Accepting tokens must implement the onOP20Received callback.
Calldata and BytesWriter patterns example
The following examples provide a brief reminder of working with Calldata and BytesWriter:
Patterns examplesassemblyscript
// How to encode the Calldata parameters
// 1st parameter: selector (method to call)
// 2nd parameter: address1
// 3rd parameter: amount1
const calldata = new BytesWriter(
SELECTOR_BYTE_LENGTH +
ADDRESS_BYTE_LENGTH +
U256_BYTE_LENGTH);
calldata.writeSelector('FUNCTION SELECTOR HERE');
calldata.writeAddress(address1);
calldata.writeU256(amount1);
// How to decode BytesWriter return values
const response = Blockchain.call(token, calldata);
if (response.data.byteLength != 0){
thow new Revert('Invalid response.');
}
// Decode response
const value = response.data.readU256();
const name = response.data.readStringWithLength();OP20 Abstract Class
The OP20 class is the OP_NET concrete implementation of the OP-20 standard. It implements the IOP20 interface and extends ReentrancyGuard, which provides both OP_NET base class inheritance and built-in reentrancy attack protection.
Protected methods can be overridden to implement custom logic or extend the default behavior, providing flexibility for specialized token implementations.
OP20 classassemblyscript
abstract class OP20 extends ReentrancyGuard implements IOP20 {
public name(_: Calldata): BytesWriter;
public symbol(_: Calldata): BytesWriter;
public decimals(_: Calldata): BytesWriter;
public icon(_: Calldata): BytesWriter;
public totalSupply(_: Calldata): BytesWriter;
public maximumSupply(_: Calldata): BytesWriter;
public metadata(_: Calldata): BytesWriter;
public domainSeparator(_: Calldata): BytesWriter;
public balanceOf(calldata: Calldata): BytesWriter;
public nonceOf(calldata: Calldata): BytesWriter;
public allowance(calldata: Calldata): BytesWriter;
public safeTransfer(calldata: Calldata): BytesWriter;
public safeTransferFrom(calldata: Calldata): BytesWriter;
public transfer(calldata: Calldata): BytesWriter;
public transferFrom(calldata: Calldata): BytesWriter;
public burn(calldata: Calldata): BytesWriter;
public increaseAllowance(calldata: Calldata): BytesWriter;
public decreaseAllowance(calldata: Calldata): BytesWriter;
public increaseAllowanceBySignature(calldata: Calldata): BytesWriter;
public decreaseAllowanceBySignature(calldata: Calldata): BytesWriter;
// Used for token deployments
public instantiate(params: OP20InitParameters, skipDeployerVerification: boolean = false): void;
// Overrides
protected _balanceOf(owner: Address): u256;
protected _allowance(owner: Address, spender: Address): u256;
protected _safeTransfer(from: Address, to: Address, amount: u256, data: Uint8Array): void;
protected _transfer(from: Address, to: Address, amount: u256): void;
protected _spendAllowance(owner: Address, spender: Address, amount: u256): void;
protected _callOnOP20Received( from: Address, to: Address, amount: u256,data: Uint8Array): void;
protected _increaseAllowance(owner: Address, spender: Address, amount: u256): void;
protected _decreaseAllowance(owner: Address, spender: Address, amount: u256): void;
protected _increaseAllowanceBySignature(owner: Address,spender: Address,amount: u256,deadline: u64,signature: Uint8Array): void;
protected _decreaseAllowanceBySignature(owner: Address, spender: Address, amount: u256, deadline: u64, signature: Uint8Array): void;
protected _verifySignature(typeHash: u8[], owner: Address, spender: Address, amount: u256, deadline: u64, signature: Uint8Array): void;
protected _buildDomainSeparator(): Uint8Array;
protected _mint(to: Address, amount: u256): void;
protected _burn(from: Address, amount: u256): void;
}Public Methods Reference
Description
Returns
A BytesWriter stream with the following structure:
- name: string (with length)
Description
Returns the token symbol.
This is a read-only method.
Returns
A BytesWriter stream with the following structure:
- symbol: string (with length)
Description
Returns the number of decimal places used by the token. Valid range: 0-32. A value of 0 creates indivisible tokens.
This is a read-only method.
Returns
A BytesWriter stream with the following structure:
- decimals: u8
Description
Returns the token's icon URL (http(s) or ipfs) for wallet/UI display.
This is a read-only method.
Returns
- icon: string (with length)
Description
Returns the current circulating amount of tokens.
This is a read-only method.
Returns
A BytesWriter stream with the following structure:
- totalSupply: u256
Description
Returns the maximum number of tokens that can exists.
This is a read-only method.
Returns
- maximumSupply: u256
Description
Get all token metadata in a single call.
This is a read-only method.
Returns
A BytesWriter stream with the following structure:
- name: string (with length)
- symbol: string (with length)
- icon: string (with length)
- decimals: u8
- totalSupply: u256
- domainSeparator: u8[]
Description
Returns a SHA-256 hash representing the unique domain separator. The hash must be derived from the OP712Domain structure.
Calls the protected _buildDomainSeparator() method, which provides the default implementation.
This is a read-only method.
Returns
A BytesWriter stream with the following structure:
- domainSeparator: u8[32]
Description
Returns the actual token balance for an address. Non-existent addresses return 0.
Calls the protected _balanceOf() method, which provides the default implementation.
This is a read-only method.
Parameters
- owner: Address
Returns
A BytesWriter stream with the following structure:
- balance: u256
Description
Returns the current nonce for an address. Non-existent addresses return 0.
This is a read-only method.
Parameters
- owner: Address
Returns
A BytesWriter stream with the following structure:
- nonce: u256
Description
Returns the "spender's" remaining allowance from the "owner's" account. Non-existent addresses return 0.
Calls the protected _allowance() method, which provides the default implementation.
This is a read-only method.
Parameters
- owner: Address
- spender: Address
Returns
A BytesWriter stream with the following structure:
- amount: u256
Description
Transfers amount of tokens from the caller's account to the to address with delivery confirmation for contract recipients. An arbitrary data payload can be specified.
The following validations are performed:
- Validates sender has sufficient balance.
- Rejects the zero and the dead addresses.
- Ensures contracts explicitly accept tokens and revert on failed acknowledgments.
Calls the protected _safeTransfer() method, which provides the default implementation.
Parameters
- to: Address
- amount: u256
- data?: u8[] - Optional data.
Returns
- A 0 length BytesWriter object.
Events
- Transferred : Emits a Transferred event.
Description
Transfers amount of tokens from the from address to the to address with delivery confirmation for contract recipients. An arbitrary data payload can be specified.
The following validations/actions are performed:
- Verifies and spends allowance (unless sender equals from).
- Handles infinite allowance (u256.Max) without decrementing.
- Validates sender has sufficient balance.
- Rejects the zero and the dead addresses.
- Ensures contracts explicitly accept tokens and revert on failed acknowledgments.
Calls the protected _spendAllowance() and _safeTransfer() methods, which provides the default implementation.
Parameters
- from: Address
- to: Address
- amount: u256
- data?: u8[] - Optional data.
Returns
- A 0 length BytesWriter object.
Events
- Transferred : Emits a Transferred event.
Description
Transfers amount of tokens from the caller's account to the to address.
The following validations are performed:
- Validates sender has sufficient balance.
- Rejects the zero and the dead addresses.
Calls the protected _transfer() method, which provides the default implementation.
Parameters
- to: Address
- amount: u256
Returns
- A 0 length BytesWriter object.
Events
- Transferred : Emits a Transferred event.
Description
Transfers amount of tokens from the from address to the to address.
The following validations/actions are performed:
- Verifies and spends allowance (unless sender equals from).
- Handles infinite allowance (u256.Max) without decrementing.
- Validates sender has sufficient balance.
- Rejects the zero and the dead addresses.
Calls the protected _spendAllowance() and _transfer() methods, which provides the default implementation.
Parameters
- from: Address
- to: Address
- amount: u256
Returns
- A 0 length BytesWriter object.
Events
- Transferred : Emits a Transferred event.
Description
Atomically subtract amount from the caller’s balance and reduce totalSupply by the same amount.
The following validations are performed:
- Reject burns from the zero and the dead addresses.
- Underflow protection: revert if amount > caller balance.
Calls the protected _burn() method, which provides the default implementation.
Parameters
- amount: u256
Returns
- A 0 length BytesWriter object.
Events
- Burned : Emits a Burned event.
Description
Atomically increase spender allowance permission on the owner's account for the specified amount.
The following validations/actions are performed:
- Overflow protection (caps at u256.Max).
- Rejects if spender address is the zero or the dead addresses.
Calls the protected _increaseAllowance() method, which provides the default implementation.
Parameters
- spender: Address
- amount: u256
Returns
- A 0 length BytesWriter object.
Events
- Approved : Emits an Approved event.
Description
Atomically decrease spender allowance permission on the owner's account for the specified amounts.
The following validations/actions are performed:
- Underflow protection (floors at zero).
- Rejects if spender address is the zero or the dead addresses.
Calls the protected _decreaseAllowance() method, which provides the default implementation.
Parameters
- spender: Address
- amount: u256
Returns
- A 0 length BytesWriter object.
Events
- Approved : Emits an Approved event.
Description
Atomically increase spender allowance off-chain on the owner's account for the specified amount.
The following validations/actions are performed:
- Overflow protection (caps at u256.Max).
- Rejects if spender address is the zero or the dead address.
- Rejects if signature verification fail.
Calls the protected _increaseAllowanceBySignature() method, which provides the default implementation.
Parameters
- owner: Address
- spender: Address
- amount: u256
- deadline: u64
- signature: u8[]
Returns
- A 0 length BytesWriter object.
Events
- Approved : Emits an Approved event.
Description
Atomically decrease spender allowance off-chain on the owner's account for the specified amount.
The following validations/actions are performed:
- Underflow protection (floors at zero).
- Rejects if spender address is the zero or the dead addresses.
- Rejects if signature verification fail.
Calls the protected _decreaseAllowanceBySignature() method, which provides the default implementation.
Parameters
- owner: Address
- spender: Address
- amount: u256
- deadline: u64
- signature: u8[]
Returns
- A 0 length BytesWriter object.
Events
- Approved : Emits an Approved event.
Description
Initialize the token metadata only once, immediately after deployment. After initialization, these values are immutable.
By default only the deployer may initialize. If deployer verification is skipped, a designated non-deployer may perform this one-time initialization.
Parameters
- params: OP20InitParameters
- skipDeployerVerification: boolean - default to false.
Protected Methods Reference
Warning
The following protected methods can be overridden to implement custom logic. However, this must be done with caution. Any override must ensure that OP-20 standard requirements are still met and must not break the existing implementation.
Description
Checks the balance map for the given owner address and returns the current balance, or 0 if the owner is not found.
Parameters
- owner: Address
Returns
- balance: u256 - The current balance.
Description
Checks the allowance map for the given owner and spender addresses and returns the remaining allowance, or 0 if none is set.
Parameters
- owner: Address - The owner address to look from.
- spender: Address - The spender address to look for.
Returns
- amount: u256 - The current allowance, or 0 if none is set.
Description
Performs the actual safe transfer operation for the specified amount from the from address to the to address:
- Calls the _transfer method to handle the basic transfer logic.
- Calls the _callOnOP20Received method to validate recipient acceptance.
Parameters
- from: Address
- to: Address
- amount: u256
- data: Uint8Array - Optional data.
Description
Performs the actual transfer operation for the specified amount from the from address to the to address:
- Validates from and to addresses.
- Verifies the sender has sufficient balance.
- Updates the sender and recipient balances by the transfer amount.
- Emits the Transferred event.
Parameters
- from: Address
- to: Address
- amount: u256
Description
Spends the given amount by reducing the available allowance from the allowance map:
- Skips spending when the owner is also the spender.
- Skips spending when allowance is u256.Max (infinite approval).
- Reverts when allowance is insufficient.
- Reduces the spender's allowance in the allowance map by the spent amount.
Parameters
- owner: Address
- spender: Address
- amount: u256
Description
Calls onOP20Received on the recipient contract with calldata conforming to the method specification. The method reverts:
- If no response is received.
- if the return value does not match ON_OP20_RECEIVED_SELECTOR.
Parameters
- from: Address
- to: Address
- amount: u256
- data: Uin8Array - Optional data.
Description
Performs the actual allowance increase operation for the specified amount:
- Validates owner and spender addresses.
- Increase the spender's allowance and handles overflow by capping to u256.Max.
- Emits the Approved event.
Parameters
- owner: Address
- spender: Address
- amount: u256
Description
Performs the actual allowance decrease operation for the specified amount:
- Validates owner and spender addresses.
- Decreases the spender's allowance and handles underflow by setting allowance to 0.
- Emits the Approved event.
Parameters
- owner: Address
- spender: Address
- amount: u256
Description
Performs the actual signed allowance increase operation:
- Calls _verifySignature to ensure the signature is valid.
- Calls _increaseAllowance to perform the allowance increase.
Parameters
- owner: Address
- spender: Address
- amount: u256
- deadline: u64
- signature: Uin8Array
Description
Performs the actual signed allowance decrease operation:
- Calls _verifySignature to ensure the signature is valid.
- Calls _decreaseAllowance to perform the allowance decrease.
Parameters
- owner: Address
- spender: Address
- amount: u256
- deadline: u64
- signature: Uin8Array
Description
Validates the signature and increments the owner's nonce on success:
- Signature must conform to OP20AllowanceIncrease or OP20AllowanceDecrease structure.
- Signature length must be 64 bytes.
- typeHash must be ALLOWANCE_INCREASE_TYPE_HASH or ALLOWANCE_DECREASE_TYPE_HASH.
- Reverts if the current block height exceeds the deadline block.
- Reverts on invalid signature.
Parameters
- typeHash: u8[] - The operation type hash.
- owner: Address
- spender: Address
- amount: u256
- deadline: u64
- signature: Uint8Array
Description
Constructs the domain separator buffer compliant with the OP712Domain structure, which is then used to generate the SHA-256 hash.
Returns
- domainSeparator: Uint8Array. (192 bytes)
Description
Mints new tokens to the specified address:
- Validates the recipient's address.
- Increases the recipient's balance.
- Increases the total supply.
- Reverts if the maximum supply is exceeded.
- Emits the Minted event.
Parameters
- to: Address
- amount: u256
Description
Burns existing tokens from the specified address:
- Validates the owner's address.
- Decreases the recipient's balance.
- Decreases the total supply.
- Reverts if the burn amount exceeds the balance.
- Emits the Burned event.
Parameters
- from: Address
- amount: u256
Events
The OP20 class emits the three OP-20 standard events: Approved, Burned, and Transferred.
Additionally, the OP20 class emits a Minted event, which is specific to this implementation and is implemented by the MintedEvent class.
Eventsassemblyscript
class ApprovedEvent extends NetEvent {
constructor(owner: Address, spender: Address, amount: u256);
}
class BurnedEvent extends NetEvent {
constructor(from: Address, amount: u256);
}
class MintedEvent extends NetEvent {
constructor(to: Address, amount: u256)
}
class TransferredEvent extends NetEvent {
constructor(operator: Address, from: Address, to: Address, amount: u256);
}
Description
Emitted when allowance is modified through any method.
The following OP20 methods emits this event in their provided implementations:
- increaseAllowance
- decreaseAllowance
- increaseAllowanceFromSignature
- decreaseAllowanceFromSignature
Parameters
- owner: Address - Token owner.
- spender: Address - Authorized spender.
- amount: u256 - New total allowance (not delta).
Description
Emitted when tokens are permanently removed from circulation, decreasing total number of tokens in circulation (totalSupply).
The following OP20 methods emits this event in their provided implementations:
-
burn
Parameters
- from: Address - Address losing tokens.
- amount: u256 - Number of tokens destroyed.
Description
Emitted when new tokens are created, increasing total number of in circulation (totalSupply).
The following OP20 methods emits this event in their provided implementations:
-
_mint
Parameters
- to: Address - Recipient of new tokens.
- amount: u256 - Number of tokens created.
Description
Emitted on all successful transfers.
The following OP20 methods emits this event in their provided implementations:
- safeTransfer
- safeTransferFrom
- transfer
- transferFrom
Parameters
- operator: Address - Who initiated the transfer.
- from: Address - Source of tokens.
- to: Address - Destination of tokens.
- amount: u256 - Number of tokens transferred.
Callbacks
The IOP20Receiver interface is not implemented by the OP20 abstract class. Instead, derived classes must provide their own implementation.
IOP20Receiver concrete implementation exampleassemblyscript
interface IOP20Receiver {
onOP20Received(callData: Calldata): BytesWriter;
}
// Example
@final
export class ContractEx extends ReentrancyGuard implements IOP20Receiver {
...
public override execute(method: Selector, calldata: Calldata): BytesWriter {
let writer: BytesWriter;
switch (method) {
case encodeSelector('onOP20Received(address,address,uint256,bytes)'):
return this.onOP20Received(calldata);
default:
return super.execute(method, calldata);
}
return writer;
}
public onOP20Received(calldata: Calldata): BytesWriter {
const operator = calldata.readAddress();
const from = calldata.readAddress();
const amount = calldata.readU256();
const data: Uint8Array = calldata.readBytesWithLength();
// Custom logic here if needed
...
const writer = new BytesWriter(SELECTOR_BYTE_LENGTH);
writer.writeSelector(ON_OP_20_RECEIVED_SELECTOR);
return writer;
}
...
}Data Structures
Concrete Implementations
- OP20InitParameters
Description
The token metadata used to initialize the token when calling the instantiate() method during deployment.
Parameters
- maxSupply: u256
- decimals: u8 - Valid range: from 0 to 32.
- name: string
- symbol: string
- icon: string - Any valid URL (http(s) or ipfs). Default to empty string when not specified.
Type Definitions
Type definitions only, not concrete implementations:
- OP712Domain
- OP20AllowanceIncrease
- OP20AllowanceDecrease
These type definitions define the data schema used by methods for signature validation and hash generation, such as signed allowance operations and the domainSeparator method.
Refer to the OP-20 Standard specification for detailed definitions.