Operations
Designed to be flexible and adaptable to different needs
Last updated
Designed to be flexible and adaptable to different needs
Last updated
Operations of ORC-20 comprises basic events including deploy, mint, send, cancel, upgrade, and custom events. You can add new keys to the standard event to introduce constraints, various behaviours, or new operations.
Each operation are inscription data with key-value pair, by default in JSON format. Operation keys must lowercase, value data are case-insensitive.
By inscribing a deploy event, you deploy an ORC-20 and must hold the deploy inscription to obtain the ownership of the ORC-20. The ownership grants permission to upgrade ORC-20 later.
Basics
| Key | Required | Description |
|---|---|---|
Advanced
| Key | Required | Description |
|---|---|---|
Example of New ORC-20: Deploy upgradable ORC-20: $ORC, max supply of 21,000,000, limit 10,000 per mint
Example of Migration: Deploy non-upgradable ORC-20: $ORC with (inscription number #2504160) , and copy the metadata such as max and lim from the original BRC-20, and convert it into ORC-20.
Inscribe mint event to minter's address to initialize a balance. Before inscribing send event, you can pass it (send ordinal) to other addresses to transfer the full amount on the ordinal. The full amount will be added to the remaining balance of the receiver.
Mint ordinals keep the initial balance. After the completion of the first send transaction, all preceding mint ordinals will be in an invalid state. Amount of any valid mint ordinals received after the send transaction will be added to the remaining balance of the receiver.
Mint event will be invalid if it exceeds the max supply of ORC-20. (Important to eliminate the possibility of double spending, different from BRC-20)
Example: mint 10,000 $ORC. 1. Mint event maintains the initial balance. 2. Minter must keep the mint inscription until the first send transaction is made.
You can inscribe send event to multiple receivers and send the remaining balance to the sender. Each send event is a partial transaction. You can cancel any or all partial transactions before the final step of send operation. You must include nonce in each send /cancel event to indicate a specific partial transaction.
After the completion of a transaction, the new balance of the sender should be updated with the balance send back to the sender. The inscription which maintains the balance of the sender is invalidated. The sent amount to the receiver are added to total balance of the receiver.
ORC-20 send transaction takes UTXO approach, key difference between BRC-20. Wallets or marketplaces implementing ORC-20 should wait for the completion of all partial transactions in a UTXO.
Example: send 1,000 $ORC (inscription number #2504160) in two partial transactions. Each transaction must have unique nonce.
Step 1: sender inscribes 1,000 $ORC (nonce 5) on "send inscription" to sender's address
Step 2: sender inscribes the "send remaining balance" back to sender
A transaction is only complete after the remaining balance is sent.
Step 3: Sender sends satoshis which contain the "send inscription" created in Step 1 to receiver
Reusing "send inscription" as long as the balance is not spent - Instead of inscribing "send event" each time when you transfer ORC-20 funds, you can pass the previously received "send ordinal" to the receiver's address to transfer the full amount on the "send ordinal", as long as the amount is not spent. The full amount will be added to the remaining balance of the receiver.
The goal is to reuse the one-time "send" inscription and reduce massive wastage on Bitcoin, and ultimately save block space and transaction fees.
Cancel any or all partial transaction by specifying nonce or a set of nonces. You can only cancel partial transactions before the finally step of the send operation. The rest of partial transactions remain valid.
Example 1: cancel the partial transaction with nonce 5.
Example 2: cancel multiple partial transactions with nonce 6, 7, 8. (advanced)
ORC-20 is a flexible standard that allows the deployer to upgrade it as needed. This feature ensures that ORC-20 can adapt to changing requirements and improve its functionality over time. Only the deployer can upgrade ORC-20.
(Important: OIP-6 has been accepted: upgrade requires a 2-step process)
The upgrade now requires a 2-step process:
Step 1. Deployer inscribes "upgrade inscription" to deployer's address
Step 2. Deployer needs to send the "upgrade inscription" to the designated validation address
Taproot: bc1pgha2vs4m4d70aw82qzrhmg98yea4fuxtnf7lpguez3z9cjtukpssrhakhl
.sats Name: orc20🔥.sats
.oid Name: orc20🔥.oid
Prerequisite: Deploy upgradable ORC-20
When you deploy ORC-20, it is upgradable by default, unless explicitly set ug to false.
Example: deploy $ORC upgradable ORC-20 (demonstration only)
Step 1: Upgrade ORC-20
Deployer must inscribe an Upgrade inscription to the Deployer's wallet address
Upgradable ORC-20 allows deployer to modify constraints or adding/removing attributes in future, such as modify max supply, mint limit. You can upgrade ORC-20 by inscribing an upgrade event.
You cannot upgrade a non-upgradable ORC-20. However, you can change an upgradable ORC-20 to non-upgradable and make it immutable (this is irreversible).
Example: upgrade max supply to 2,100,000, and mint limit to 1,000, and make it non-upgradable to prevent any future modification. (demonstration only)
Step 2: Validate the Upgrade
Deployer needs to validate the upgrade by sending the Deployment inscription to this Designated Address
Taproot: bc1pgha2vs4m4d70aw82qzrhmg98yea4fuxtnf7lpguez3z9cjtukpssrhakhl
.sats Name: orc20🔥.sats
.oid Name: orc20🔥.oid
Use Cases:
Decrease mint limit over time to create digital scarcity to emulate Bitcoin halving
Increase max supply and reward additional incentives to community members
Initially provide a special minter address to mint a portion to the DAO treasury, and change the mint limit for community minting
Deployer inscribes listing event to help holders and marketplaces identify a collection of authentic inscriptions.
Example: include inscriptions 2713750, 2713751 in the collection
Use Cases:
Deployers can provide additional clarity and exclude invalid mints like bad json format, over mints etc.
eg. Yuga Labs may list all authentic mints to holders and marketplaces
| Key | Required | Description |
|---|---|---|
| Key | Required | Description |
|---|---|---|
| Key | Required | Description |
|---|---|---|
| Key | Required | Description |
|---|---|---|
| Key | Required | Description |
|---|---|---|
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size and case-insensitive, eg. ORC = orc
name
no
Name: name of ORC-20 in any size
id
no
Identifier: inscription number.
Subsequent operations must use inscription number (improvement proposed OIP-3 by @t4t5).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: deploy event, specify type of event, eg. deploy, mint, send, cancel
max
no
Max Supply: set max token supply, default to infinite unless explicitly specify, limited to uint256
lim
no
Mint Limit: max amount can be minted per ordinal, default to 1
dec
no
Decimal: decimal precision must be <=18, default to 18
ug
no
Upgradable: true or false, default to true. It allows the deployer to upgrade ORC-20 later.
wp
no
Migration Wrapper: true or false, default to false. This is for token migration purpose and irreversible. Only the deployer of the original BRC-20 can deploy migration event. The wrapper copies metadata of the original BRC-20, eg. same max supply, mint limit.
v
no
Version: helpful information when you upgrade the ORC-20.
msg
no
Message: custom text, message, manifesto in any size
Custom Key
no
For custom implementation only, eg. tax - to enforce transactional tax, such as royalties; minter - special minter address; img - token image; tkid - token id; url - url of token info
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size, eg. ORC = orc
id
yes
Identifier: inscription number.
Subsequent operations must use inscription number (OIP-3).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: mint event, specify type of event, eg. deploy, mint, send, cancel
amt
yes
Mint Amount: specify the amount to mint, cannot exceed the mint limit set in deploy event
msg
no
Message: custom text, message, manifesto in any size
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size, eg. ORC = orc
id
yes
Identifier: inscription number.
Subsequent operations must use inscription number (OIP-3).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: send event
(Use send or transfer compatible with BRC-20 OIP-2)
Type of event: eg. deploy, mint, send, cancel.
n
yes
Nonce: keep track of each partial transaction
amt
yes, when sender is not receiver
Send Amount: always set amount If sender is not the receiver; default to the remaining balance when sending back to sender.
msg
no
Message: custom text, message, manifesto in any size
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size, eg. ORC = orc
id
yes
Identifier: inscription number
Subsequent operations must use inscription number (OIP-3).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: cancel event
Type of event: eg. deploy, mint, send, cancel.
n
yes
Nonce: Array of nonce(s) partial transaction(s)
msg
no
Message: custom text, message, manifesto in any size
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size, eg. ORC = orc
id
yes
Identifier: inscription number.
Subsequent operations must use inscription number (OIP-3).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: upgrade event
Type of event: eg. deploy, mint, send, cancel.
max
no
Max Supply: modify maximum supply, limited to uint256
lim
no
Mint Limit: modify max amount can be minted per ordinal
dec
no
Decimal: modify decimal precision, must be <=18
v
no
Version: recommended when you upgrade the ORC-20
ug
no
Upgradable: true or false
msg
no
Message: custom text, message, manifesto in any size
Custom Key
no
For custom implementation only, eg. tax - to enforce transactional tax; minter - special minter address.
p
yes
Protocol: orc-20 or orc20 case-insensitive. (OIP-1)
For wider adoption, any ordinal tokens supporting ORC-20 implementation (like src-20, xrc-20, including wrapped BRC-20) can be included.
tick
yes
Ticker: symbol of ORC-20 in any size, eg. ORC = orc
id
yes
Identifier: inscription number
Subsequent operations must use inscription number (OIP-3).
eg. initial ORC-20 deployment doesn't require id; but you must specify inscription number of the deployment for subsequent mint, send, migration, and upgrade.
op
yes
Operation: list event (effective only by the deployer) describes a collection of authentic inscriptions.
Type of event: eg. deploy, mint, send, cancel.
coll
no
Collection: array of inscription numbers (no #)
msg
no
Message: custom text, message, manifesto in any size
url
no
URL: additional information of the collection