Introduction

What is the Atomicals Protocol?

The Atomicals Protocol is a simple, yet flexible protocol for minting, transferring and updating digital objects (traditionally called non-fungible tokens) for unspent transaction output (UTXO) blockchains such as Bitcoin. An Atomical (or "atom") is a way to organize the creation, transfer and updates of digital objects – it is essentially a chain of digital ownership defined according to a few simple rules.

Why use Atomicals?

The Atomical specification is the simplest possible way to organize digital property on a blockchain such as Bitcoin. The implementation is very simple and provides the maximum flexibility for static and dynamic digital assets, artifacts and objects. The rules are so simple that it's impossible to accidentally spend Atomicals as miner fees and it's trivial to verify that ownership was transferred to the correct recipient – without relying on any third parties whatsoever or even being required to run an indexer. Atomicals are self-evident digital object histories. That being said, most developers and services will prefer the convenience of running their own indexer and all the benefits that come along with it.

Use Cases

• Digital collectibles, media and art
• Digital identity, authentication and token- gated content.
• Web hosting and file storage
• Peer to peer exchange and atomic swaps
• Digital namespace allocation
• Virtual land and title registries
• Dynamic objects and state for games
• Social media profiles, posts and communities
• Anywhere security and decentralization is critical concern. Military grade security and verification requirements.

The usage philosophy of Atomicals is to pass along the complete history of an Atomical digital object from mint inception and including every transfer updates. Even if an Atomical is updated or exchanges hands 10,000 times – that amounts to only about 2.5 MB of data (250 bytes x 10,000). A digital object is self-evident, unforgeable chain of authenticity that does not rely on any third party service or centralized indexer for verification purposes.

The motto is:

"No transaction history, not your digital object"

Any client, wallet, marketplace, game and service can rapidly verify the Atomical by processing the history according to the very simple rules and detect a fake instantly without relying on trusted services.

The heart of Atomicals is a few key simple rules to follow for mint, transfer, and update operations, continue reading to the Protocol Overview to understand the high level flow before diving deeper. If you like, you can just skip all the theory and go straight to minting your first Atomical within a couple of minutes.

What are Atomicals Digital Objects?

An Atomical digital object (or simply "Atomical") is a new kind of Non-Fungible Token (NFT) that can be minted, transferred, and updated on Bitcoin. The major difference is there is no requirement to use a centralized service or middleman acting as a trusted indexer. It just works today and without needing changes whatsoever to Bitcoin nor requiring side-chains or any secondary layers. It is time to take back control of our digital lives - forever.

Atomicals are self-evident and easy to verify which makes them perfect for digital collectibles, social media, gaming, authentication and anywhere ownership and authenticity is critical to establish. The protocol rules are extremely simple, yet at the same time provides military grade security and verification levels. Zero room for error.

The Atomicals Protocol is free, open-source and will forever be available to use by anyone anywhere. Our digital future depends on a robust digital object format to elegantly handle every possible use case while minimizing any potential for errors in software implementations.

The Atomicals Vision

The grand vision is to establish and secure the Bitcoin blockchain as the source of truth and digital sovereignty. Atomicals provides a simple and powerful protocol to take back control of our digital lives forever. We have everything within reach for us to create the future we want.

The Atomicals Protocol is open source, free for anyone to use however they want. All the libraries, frameworks and services are released under MIT and GPLv3 to ensure no one has power over the tools and protocol.

This is our work of passion to give to the world an option for finally bringing programmable digital objects to Bitcoin. It works today with no changes to Bitcoin, no side-chains, no separate token, no secondary layers and no middlemen, no leaders nor centralized parties.

It is designed to work in harmony with the other protocols that have emerged such as Nostr, Ordinals and more. Each Protocol has it's different strengths and Atomicals Digital Objects adds to the landscape of options available for users, creators and developers.

Atomicals is a shift to sovereignty and self-ownership over our digital lives. A simple and extremely powerful protocol to re-decentralize the web and social communities.

Key Differences From Other Protocols

The best way to understand the differences of Atomicals is to compare it against other popular non-fungible token (NFT) protocols.

Atomical Numbers, IDs, REFs

An Atomical Number is a sequential numbering scheme starting from 0. The numbering scheme is used to give a global order of the Atomicals that were minted. The Atomicals numbering scheme provides a simple way to refer to individual Atomicals with a short number that complements the Atomical ID.

Atomicals have the Atomical ID which is a unique identifier based on the hash and output of the transaction it was minted in such as <txid>i<index> (Example: a14e65573ff32b95b91a0ed8367feec64125e5f4ff44d9901002b262da959e6di0). In contrast, the Atomical number is the sequential ordering of every Atomical that was minted, in the order they appear in the blockchain.

An Atomical Reference ("REF" for short) is an alternative encoding of the Atomical ID using Crockford-base32 to provide a richer character set to make it more useful for vanity identifiers. (See section on 'Bitwork')

Get Started and Create Your First Atomical Digital Object

Download and install the Atomicals Javascript CLI tool and mint your first Atomical in less than 2 minutes.

description: Atomicals Digital Objects or "atoms" for short.

NFTs

What are Atomicals Digital Objects?

An Atomical digital object (or simply "Atomical") is a new kind of Non-Fungible Token (NFT) that can be minted, transferred, and updated on Bitcoin. The major difference is there is no requirement to use a centralized service or middleman acting as a trusted indexer. It just works today and without needing changes whatsoever to Bitcoin nor requiring side-chains or any secondary layers. It is time to take back control of our digital lives - forever.

Atomicals are self-evident and easy to verify which makes them perfect for digital collectibles, social media, gaming, authentication and anywhere ownership and authenticity is critical to establish. The protocol rules are extremely simple, yet at the same time provides military grade security and verification levels. Zero room for error.

The Atomicals Protocol is free, open-source and will forever be available to use by anyone anywhere. Our digital future depends on a robust digital object format to elegantly handle every possible use case while minimizing any potential for errors in software implementations.

How Atomicals Digital Objects Are Created

An Atomical is minted using a 2-step commit and reveal scheme using Taproot (P2TR) spend scripts using the Atomicals Envelope and the minting operation denoted by the letter "m". A transaction output commits to the data or file being commuted and then the data is included in a spend script to reveal the content which could one or more files with any content type such as images, text or any media.

Mint your first Atomical using the command line interface with nothing more than your existing Bitcoin wallet.

Once created the Atomical is stored on the blockchain forever immutably and may be transferred using any address type to any new owner according to the familiar rules of Bitcoin.

How Atomicals Digital Objects Are Updated

In addition to immutable content and files, Atomicals digital objects supports the ability to attach any number of files and state at any time after using the update operation denoted by the letter "u". Similar to the minting operation, the update follows a 2-step commit and reveal scheme to commit to an update and then a P2TR taproot spend script reveals the update contents.

Any file or content type is supported in a single update. The owner of the digital object can overwrite, or update, the content of any file. This gives Atomicals a unique capability to act as an evolving data object perfect for social media, games, and more.

Due to the nature of immutable storage, every file has the revision history stored permanently to be able to playback the state changes with fidelity.

How Atomicals Digital Objects Are Transferred

An Atomical, once minted, is transferred like regular Bitcoins using any address format type include Taproot (P2TR), SegWit, Multisig, and legacy address (P2PKH).

No special wallet support is required, although it is highly recommended to use an Atomicals-aware wallet to help facility identifying and transferring Atomicals safely. Even though it is impossible to accidentally destroy an Atomical, it is possible to send it to an unintended recipient if the user is not careful using a wallet that does not facilitate Atomicals identification. Fortunately the implementation is the simplest possible protocol that makes it easy for wallets and services to do if correctly and avoiding errors.

There is no separate explicit "Transfer Operation" because we rely on using the native Bitcoin transfer mechanism to flow (or imprint) the identity of an Atomical from the inputs to the outputs.

Read about NFT Transfer Rules and NFT Swap Rules.

Dynamic Digital Object State

An overview of how to update the data state of an AtomicalEvery NFT Atomical digital object has not only the immutable static files embedded upon minting, but it also has the ability to attach any data or file throughout it's lifetime. Since Bitcoin is an immutable audit trail, every change to every field is permanently recorded and can be played back to verify the latest state was arrived at correctly.What this means is that we finally have a way to create complex interactions, games and other services that depend upon attaching data to NFTs. The Atomicals payload format is intuitive and simple: add one or more files or variables to every spend of the digital object UTXO and like magic the latest state is propagated to all nodes and served up in the indexer instantly.With one simple command users and programmers can set key-value pairs of any type of data and even larger files like PDFs and images. For example, a user can host their BTC wallet address at the path "/btc/address" and host their avatar picture at "/profile/photo" in their Atomical and update it easily.The Atomicals philsophy is "Not your digital object history, not your digital asset", which means that we "Trust, but verify" and it's easy to validate the object state is correct by playing forward the history. Don't worry, we are providing a full suite of tools and libraries to basically do all of this automatically for you on launch day.\

⚡ Get started and mint your first Atomical Digital Object

Download and install the Atomicals Javascript CLI tool and follow the quick start instructions

description: Learn about Atomicals Non-Fungible Tokens (NFT) Transfer Rules

Normal Transfer Rules

The normal operation of an NFTs such as Realms and containers is using First-In First-Out (FIFO) allocations from inputs to outputs. The way to imagine as the the earliest inputs which contain NFTs will go to the first available output, then the next inputs which contain NFTS go to the next output, and so on until all the input NFTs have been allocated. In the case that an expected output is an unspendable OP_RETURN or there are not enough outputs to accomodate the input sequence, then the NFTs are always assigned to the 0'th output.

Transfers of Non-Fungible Tokens (NFT)

NFT inputs are assigned in a First-In First-Output approach. In the case of an input containing multiple NFTs they are considered at the same position and will be assigned to the same output together.

description: Learn about Atomicals Non-Fungible Tokens (NFT) PBST Swap Rules

Swap Transfer Rules

STEP 1.
Seller signs 2nd input containing the NFT Atomical 7771 and 2nd output to receive 4000 Satoshis.
Signing with SIGHASH_SINGLE | ANYONECANPAY allows the buyer to add additional inputs for funding and their receive address for where to receive the NFT

STEP 2.
Buyer adds funding input at 1st input and adds first output to receive the NFT Atomical 7771 value. Signing with SIGHASH_ALL commits the buyer to all inputs and outputs.

description: >- Separate (or "splat") merged NFTs at the same UTXO location to their own outputs

Splat Operation

In the event that NFTs were merged to the same UTXO location, use the SPLAT(x) operation to quickly seperate all of them in a single transaction.

Examples:

Atomicals 1199 ,4567, 0542 are Non-Fungible Tokens (NFT) merged in a single UTXO.

To separate them, use the SPLAT (x) operation to spread them out over the outputs in alphabetical order according to their atomical_id.

If there are not enough outputs to accommodate the remaining NFTs, or the corresponding output is an unspendable OP_RETURN, then that particular NFT is automatically assigned to the first Output 0 always.

\

\

description: Fungible Token colored coin standard backed by Satoshis

ARC20 Tokens

The Atomicals Protocol solves the long standing problem of how to represent arbitrary fungible token assets on the Bitcoin blockchain. The ARC-20 fungible token standard finally brings colored coins to Bitcoin and uses each Satoshi to represent ownership units of deployed tokens. This means that every unit of the token is backed by 1 Satoshi forever. It acts as a kind of "digital gold content" that underpins the value of the token. It also means every token can never go below 1 Satoshi in value, by definition.

ARC-20 uses the native Satoshi unit to represent each token, and they can be split and combined just like regular Bitcoins. ARC-20 tokens can be minted by anyone, and transferred to any Bitcoin address type, and works with wallets that support UTXO selection such as Sparrow Wallet (external link). There are two modes of deployment: direct and decentralized. Learn more below about the different ways the ARC-20 can be minted and their benefits.

The ARC-20 also comes with a built in ticker symbol service to provide a global unique name system for ticker symbols. The first registration of the ticker name is permanent and can never be used again.

Decentralized Mint

A decentralized is initialized with a ticker, per mint award, total mints allowed, start block height, and metadata. A deployer could initialize a ticker such as $myticker123 with a mint award of 1,000 units, with a total of 10,000 mints allowed and starting at block height 810,000 with an image.jpg and even meta data such as description, links, and terms.

Initialize (init-dft)

The basic format of the decentralized initialization using the Atomicals CLI is given as:

yarn cli init-dft <tick> <per_mint_amt> <mint_count> 
<start_height> metadata.json

Optional flags:
--mintbitworkc=<prefix>
--satsbyte=<number>

See format of metadata.json below

The decentralized initialize function init-dft allows minting for ticker tick to proceed with the mint-dft command (described below) only from the starting block height start_height and allowing a maximum of mint_count total mint requests, each to award per_mint_amt token units to the requester. The effective total max supply is per_mint_amt * mint_count.

Note: It will take 3 block confirmations before the tick ticker will be claimed. You can query the status with yarn cli get <atomicalID> or yarn cli find-tickers

Required Parameters:

tick: The globally unique ticker name

per_mint_amt: Number of units of the token to award per successful mint. Satoshi amount.

mint_count: Total number of permitted mints before exhausting the quota and becoming "fully minted"

start_height: Starting block height that mints may be begin. Can set block height to 0 or any future block height.

image: An image icon to represent the token. The name of the file will appear in the token. Use caution and rename the file first completely and include it as "image.jpg" or "image.png"

Optional Flags:

--mintbitworkc=<prefix>

Define an optional Bitwork mining prefix target for the mints. If set, then the minters must expend CPU energy to find a match for the prefix target to be allowed to mint successfully. This forces minters to perform proof of working mining in a similar manner to Bitcoin mining itself.

It is recommended to choose a prefix between 4 and 6 hex digits. You can use any valid hex digits between a-f0-9. It is intended to purely be a vanity transaction id and any value is sufficient to require minters to expend energy to mint the token.

Example time estimates for time required for minters:

Note: it could be any digit in the range a-f0-9, we use all 7's for illustration purpose only.

• 3 hex digit prefix of "777" will take about 4 seconds to mine
• 4 hex digit prefix of "7777" will take ~1 minute to mine
• 5 hex digit prefix of "77777" will take ~16 minutes to mine
• 6 hex digit prefix of "777777" will take ~256 minutes to mine

--satsbyte=<number>

Set the satoshis per byte for the transaction and override the default.

Initialize a Perpetual Minting token

yarn cli init-dft-perpetual <ticker>

Important Optional Parameters:

• max_mints: The number of mints allowed per mint phase. (Defaults to 2000)
• maxglobalmints: The number of global max mints.
• mint_amount: The number of tokens per mint. (Defaults to 10000)
• mint_height: The starting mint height.
• mintbitworkvec: The base vector of the bitwork prefix.
• mintbitworkcinc: The amount of bitworkc to increase for each phase of max_mints. (Defaults to 1)
• mintbitworkrinc: The amount of bitworkr to increase for each phase of max_mints.
• mintbitworkcincstart: The starting amount of bitworkc to increase for each phase of max_mints.
• mintbitworkrincstart: The starting amount of bitworkr to increase for each phase of max_mints.

See the complete arguments list using the command yarn cli init-dft-perpetual -h.

Below is an example of how to initialize a token with the same configuration of $infinity.

yarn cli init-dft-perpetual infinity2 \
  --max_mints=3333 \
  --mint_amount=9999 \
  --mintbitworkvec="888888888888888888888888" \
  --mintbitworkcinc=1

In mathematical terms, the relationship between the arguments in the function can be expressed as follows:

1. Target Calculation:

   • ( T_{\text{steps}} = \lfloor \frac{\text{actual_mints}}{\text{max_mints}} \rfloor )
   • ( T_{\text{current}} = \text{starting_target} + (T_{\text{steps}} \cdot \text{target_increment}) )

   The current target, ( T_{\text{current}} ), is computed based on the number of minted tokens relative to the maximum allowable mints, scaled by the target increment.

2. Bitwork Prefix Derivation:

   • ( \text{multiples} = \frac{T_{\text{current}}}{16} )
   • ( F_{\text{amount}} = \lfloor \text{multiples} \rfloor )
   • ( \text{modulo} = T_{\text{current}} \mod 16 )

   The resulting bitwork prefix string is derived from the base vector ( \text{bitwork_vec} ), padded to 32 characters, with:

   • The first ( F_{\text{amount}} ) characters forming the primary prefix.
   • If ( \text{modulo} > 0 ), it appends (".\text{modulo}") to the prefix.

Mint (mint-dft)

The basic format of the decentralized mint using the Atomicals CLI is given as:

yarn cli mint-dft <tick>

Optional flags:
--satsbyte=<number>

The decentralized mint function mint-dft allows minting for ticker tick to proceed starting from block height start_height.

Follow the on-screen instructions to mint.

Required Parameters:

tick: The globally unique ticker name

Optional Flags:

--satsbyte=<number>

Set the satoshis per byte for the transaction and override the default.

Direct Mint

The second way to mint or create an ARC-20 token type is to directly create a single output which contains the total supply, with each Satoshi representing a single unit of the token.

Mint entire supply in one step

yarn cli mint-ft <tick> <total_supply> metadata.json

Optional flags:
--satsbyte=<number>

See format of metadata.json below

The second way to mint or create an ARC-20 token type is to directly create a single output which contains the total supply, with each Satoshi representing a single unit of the token.

For example, to mint a token with a supply of 100,000,000, simply create a single output with exactly 1 full Bitcoin (since 1 BTC = 100,000,000 Satoshis). An advantage of using the direct minting mode is that the team who creates it must put up the required amount of Bitcoins to substantiate the total minted supply; which greatly reduces dishonest actors from printing tokens out of thin air.

Direct minting of ARC-20 is ideal for when a team or company wishes to maintain control over the initial distribution and determine how to spend the tokens at a later point in time.

Note: It will take 3 block confirmations before the tick ticker will be claimed. You can query the status with yarn cli get <atomicalID> or yarn cli find-tickers

Required Parameters:

tick: The globally unique ticker name

total_supply: Total supply units to directly mint

image: An image icon to represent the token. The name of the file will appear in the token. Use caution and rename the file first completely and include it as "image.jpg" or "image.png"

Optional Flags:

--satsbyte=<number>

Set the satoshis per byte for the transaction and override the default.

Metadata.json Format

Define metadata details into the token. The suggested format to use follows the convention sample-ft-meta.json.

Use Permanent File Storage to store an image on-chain and reference it in the "image" field below.

```json
{
    "name": "",
    "desc": "",
    "image": "atom:btc:dat:<location of store-file data>/image.png",
    "decimals": 0,
    "links": {
        "x": {
            "v": "https://x.com/..."
        },
        "website": {
            "v": "https://..."
        },
        "realm": {
            "v": "atom:btc:realm:myrealmname.subrealm"
        },
        "discord": {
            "v": "https://discord.gg/..."
        }
    },
    "legal": {
        "terms": ""
    }
}
```

None of the fields in the metadata are required, and can take any shape and form as long as it is valid JSON object. However it is recommended at a minimum name, description, and legal are provided to inform users of usage details. You must consult legal advice and verify your applicable jurisdictions permit your intended usage.

description: Learn about Atomicals Fungible Tokens (ARC20) Transfer Rules

Normal Transfer Rules

The normal operation of an ARC20 token transfer is that the sum total of all the input values should be allocated completely, or cleanly, into the available outputs. In the situation that there are not enough output values, or one of the subsequent outputs would result in an overallocation (ie: inflation of the token units), then the remaining balance is permanently destroyed or burned.

Transfers of Fungible Tokens (ARC20)

Fully allocating - cleanly assign all inputs to outputs with FIFO rule.

Atomicals 1932 ,7920, 0542 are Non-Fungible Tokens (NFT) are assigned in First-In First Out order while skipping unspendable outputs (OP_RETURN). The first input NFTs are assigned starting from Output 0, and then each subsequent NFT input assigned to the next available output.
Multiple Atomicals at the same UTXO input are sorted by atomical_id. Since “1932” is before “7920” it goes first.

Transfers of Fungible Tokens (ARC20)

Not cleanly allocating - Performs "best effort" assignment for all tokens from Output 0

In the case that the outputs cannot be fully (or "cleanly") assigned, then the algorithm attempts to allocate all ARC20 tokens starting from Output 0, regardless of whether another ARC20 was already allocated. This decision was made to give leniency in the event that the developer or wallet accidentally failed to track multiple input ARC20 - in other words a "best effort" attempt is made to compensate and assign.\

Atomicals 1932 ,7920, 0542 are Non-Fungible Tokens (NFT) are assigned in First-In First Out order while skipping unspendable outputs (OP_RETURN).

If they Atomicals cannot be “cleanly assigned”, as in the example above the 5th output has 700 units (which is too much for the Atomical 0542’s value of 620), then the algorithm defaults to “best effort” assigning all ARC20 starting from Output 0.

Transfers of Fungible Tokens (ARC20)

Insufficient outputs - permanently destroying unallocated units

Atomical 86a1 is Fungible Tokens (ARC20) and can be split and merged across outputs.

An Atomical is insufficiently allocated when there is not a sufficient amount of Satoshis in the outputs to accommodate the input values. The result is the excess input value is burned – or permanently destroyed. The example above shows that Atomical 86a1’s input value is 2600, but there are only 1600 Satoshis in the outputs, which effectively results in 1000 units of Atomical 86a1 being burned.\

Transfers of Fungible Tokens (ARC20)

Incorrect over-allocation - permanently destroying remainder

Atomical 86a1 is Fungible Tokens (ARC20) and can be split and merged across outputs.

An Atomical is incorrectly allocated when there is an excess of Satoshis in the expected output and there is not enough remaining balance of the inputs for the Atomical. The example above shows that Atomical 86a1’s input value is 2600, and there is 600 in the first output, but the second output has 2100 Satoshis, which cannot take on the Atomical 86a1 because there is only 2600 - 600 = 2000 units of the Atomical remaining to allocate. To attempt to allocate would result in inflation of the supply and therefore is considered invalid. The result is that 2000 units of Atomical 86a1 is permanently destroyed

description: Learn about Atomicals Fungible Tokens (ARC20) PBST Swap Rules

Swap Transfer Rules

STEP 1.
Seller signs 2nd input containing the ARC20 Atomical 9810 and 2nd output to receive 5000 Satoshis. Signing with SIGHASH_SINGLE | ANYONECANPAY allows the buyer to add additional inputs for funding and their receive address for where to receive the ARC20 tokens.

STEP 2.
Buyer adds funding input at 1st input and adds first output to receive the ARC20 Atomical 9810 value. Signing with SIGHASH_ALL commits the buyer to all inputs and outputs.

description: This is only a PRELIMINARY CONCEPT and no implementation exists to date.

Substantiation Factor

❗ This is only a PRELIMINARY CONCEPT and no implementation exists to date.

Problem: It is not possible to transfer less than 546 satoshis in a single UTXO with Bitcoin due to the dust limit, and therefore it is not possible to transfer ARC20 tokens in denominations less than 546, which can be prohibitive for many users and applications.

⚡ Solution: Introduce a SUBSTANTIATION FACTOR (SF) that redefines how many Satoshis are needed to back a single unit of an ARC20 token. The default substantiation factor is 1:1 and arbitrary precision must be feasible to facilitate making transfers involving less than 546 units of a token.

Operation: "ST" - Substantiate Token

A new operation is created that allows the re-substantiation of token units from 1:1 to 1:10, 1:100, etc... Effectively allowing the owner of the token to "split" or "fractionalize" their token units to arbitrary precision - with one catch: they must provide the regular Satoshis as the collateral or backing of the token units direclty in proportion to their desired factor.

The default operation of ARC20 is to have 0 decimals, or a 1:1 substantation. We can define this as an Exponent of 0 in the calculation 10^0 = 1

We can then see we can "rescale" or "re-substantiation" by different factors, by changing the exponent to give decimal places.

Consider the table of Exponents to represent token units with 1:1 backing, then 1:10, then 1:100 satoshis, etc and so on.

10^0 = 1
10^1 = 10
10^2 = 100
10^3 = 1,000
10^4 = 10,000
10^5 = 100,000

For example, if we wish to trade 1 unit of a token, while still respect the dust limit. Then we simply need to substantiate each unit of the token with 1,000 regular satoshis and then we can perform a transfer of 1,000 satoshis with Exponent=3.

An example will demonstrate how this works, preserving the fungibility and fluidity of the ARC20 transfers.

In the event there are multiple inputs with different exponents, we can easily handle them too:

An example to "downscale" to a lower exponent

And one more example to demonstrate the downscaling to make the point extra clear

Transfers without Operation "ST"

When the Operation "ST" is not used, then the highest Exponent is taken as the target Exponent, that's all there is to it.

description: Overview of Collection Containers for Tokens and Data

Collection Containers

This section describes how to mint a special type of Atomical digital object called a Container. This data type is designed for NFT collections and more. Basically any time we want to group items together, we will use a container.

-> Quick Overview: What is a Container?

Containers are human-readable identifiers to represent collections of NFTs and metadata. A Container name begins with the hashtag # sign. Container names are self-owned and self-managed directly on the Bitcoin blockchain using the Atomicals Digital Object format — add and update items in the container collection, and optionally seal the container permanently to prevent future changes

📌 To Mint Container Items with DMINT (Decentralized Mint) consult the DMINT Guide

Collection Format (Recommended)

For efficiency reasons, the attributes are defined seperately from the items attributes assocations. A numeric value is used to link or connect the attributes of each item to the attribute definitions.
See the sample collection format in github.

name (string - optional)

The name field defines the display name of the collection. The collection container itself is identified with the # hashtag slug (ie: #mycollection-name), and name is what websites can use to display a more descriptive name.

desc (string - optional)

The desc field defines the detailed description of the collection.

legal (object - recommended)

The legal section defines legal terms and licensing to make it clear how users and holders of the NFTs may use the data.

terms (recommended): Any specific terms of the collection usage or items usage.

license (recommended): Any type of license code.

"legal": {
    "terms": "...",
    "license": "CC",
}

links (optional)

The links section defines additional external resources of interest such as website and social media links.

{
    "links": {
        "x": {
            "v": "https://x.com/username"
        },
        "website": {
            "v": "https://coolwebsite.com"
        },
        "discord": {
            "v": "https://discord.gg/..."
        }
    }
}

attrs (object - optional)

The attrs section defines the types of attributes, their details such as name, description and possible ranges of values.

items (object - required)

The items section connects all of the NFTs to the container using a map of key to items. It is recommended to use a string of the key of items, even when using a numbering scheme.

id (required): stands for "id" of an item and corresponds to the atomical ID of an NFT

a (required): stands for "attributes" of an item. It is required to be in the form of an array with each element in the array representing the associated value in the attributes definition section attr

n (optional): stands for "name" of an item

```json
{
  "name": "Collection Name",
  "desc": "Collection description",
  "image": "atom:btc:dat:<location of store-file data>/image.png",
  "legal": {
    "terms": "...",
    "license": "CC"
  },
  "links": {
        "x": {
            "v": "https://x.com/..."
        },
        "website": {
            "v": "https://..."
        },
        "discord": {
            "v": "https://discord.gg/..."
        }
  },
  "attrs": [
    {
      "name": "bodyarmor",
      "desc": "Type of body armor",
      "type": "string",
      "values": [
        "metal",
        "leather",
        "field"
      ]
    },
    {
      "name": "headcovering",
      "desc": "The type of head covering",
      "type": "string",
      "values": [
        "bandana",
        "helmet",
        "scarf",
        "baseball cap"
      ]
    },
    {
      "name": "stamina",
      "desc": "The stamina of the hero",
      "type": "integer",
      "min": 0,
      "max": 10
    }
  ],
  "items": {
    "0": {
      "id": "84718b469c40b1bcc7cb324b8e24e4e442f88cd913687ea2bc7b3e79d4fc4fdei0",
      "n": "Some Name",
      "a": [
        0,
        3,
        8
      ]
    },
    "1": {
      "id": "1070d7c98304bf5ac9a5addceb13e0ce4e840641f82d71d84cebbdac427c1f4fi0",
      "n": "Another Name",
      "a": [
        1,
        2,
        10
      ]
    },
    "Signature Series 1": {
      "id": "14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0",
      "n": "Special",
      "a": [
        2,
        3,
        7
      ]
    }
  }
}
```

Execute the following commands after formatting your collection data in the format above.

// first store the desired main image on chain (see section below)
yarn cli store-file ./path/to/image.png image.png --satsbyte=10

Success sent tx:  db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f
{
  "success": true,
  "data": {
    "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997",
    "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f",
    "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0"
  }
}

// We will use the dataId above to reference the data on chain
// ie: atom:btc:dat:db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0/image.png

// Store the collection metadata with the following command:
yarn cli set-container-data #mycollection-name collection.json --satsbyte=10

Bare Minimum Recommended Collection Format

If you have a collection with no attributes and not much metadata, then the following format is the recommended minimum. Provide a name, image and the list of items.

```json
{
  "name": "Collection Name",
  "image": "atom:btc:dat:<location of store-file data>/image.png",
  "items": {
    "0": {
      "id": "84718b469c40b1bcc7cb324b8e24e4e442f88cd913687ea2bc7b3e79d4fc4fdei0"
    },
    "1": {
      "id": "1070d7c98304bf5ac9a5addceb13e0ce4e840641f82d71d84cebbdac427c1f4fi0"
    },
    "9999": {
      "id": "14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0"
    }
  }
}
```

Execute the following commands after formatting your collection data in the format above.

// first store the desired main image on chain (see section below)
yarn cli store-file ./path/to/image.png image.png --satsbyte=10

Success sent tx:  db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f
{
  "success": true,
  "data": {
    "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997",
    "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f",
    "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0"
  }
}

// We will use the dataId above to reference the data on chain
// ie: atom:btc:dat:db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0/image.png

// Store the collection metadata with the following command:
yarn cli set-container-data #mycollection-name collection.json --satsbyte=10

Storing Immutable Image File on Chain

permanent-file-storage.md

Using the command line utility, execute the following command to set the data in the sample file above.

// immutably store an image on-chain to reference in the container metadata
yarn cli store-file ./path/to/image.png image.png --satsbyte=10

Success sent tx:  db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f
{
  "success": true,
  "data": {
    "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997",
    "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f",
    "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0"
  }
}

We will use the reveal location (db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0) to refer to the image image.png below.

Adding NFTs to a Collection Container

Provide a file that matches the collections format above and execute the following command to update the sample #mycollection-name.

yarn cli set-container-data #mycollection-name sample-collection.json --satsbyte=10

Querying Metadata and Items of Collection Container

After the transaction is confirmed in a block, you may query the state of the sample #mycollection-name with:

yarn cli state #mycollection-name

description: Atomicals NFT Container DMint Tutorial

DMINT Guide

The following DMINT Guide is courtesy and written by the wizz.cash team. Original link.

Terms

Overview

This tutorial is designed to help project owners quickly understand how to onboard their DMINT NFT collection onto the Atomicals protocol. In the Atomicals protocol, NFT collections are d to as 'containers', which is roughly equivalent to 'NFT collection.'

The process can be broadly divided into four main blocks:

1. Prepare all data for the collection.
2. Configure the container.
3. Validate the NFT item.
4. Mint the NFT item.

As a project owner, your focus should be on steps 1, 2, and 3.

💰 Before each step, there is a ⛓️ icon indicating that the operation is on-chain, requiring gas consumption.

Prepare Collection Data

1. Gather data for all NFTs (A1, A2......AN).
2. Prepare the DMINT data for the collection (B).
3. Collect other metadata for the collection (C).
4. Use the command-line tool to locally create a new wallet for isolating all container operations and avoiding confusion.

Configure Container

1. ⛓️ Mint the container.
2. ⛓️ Use the collection data (B) to configure DMINT.
3. ⛓️ Configure other metadata (C).
4. ⛓️ Seal the container after confirming all information. (Final step! Final step!)

Validate NFT Item

1. With existing item data and the container already on-chain with configured DMINT, independently use NFT data (A) to validate whether the item matches the container.
2. The container is sealed; you can retrieve the mint status of individual items and the list of items already minted.

Mint NFT Item

1. ⛓️ Download NFT data (A) and locally mint using the official command-line tool.

📌 For your convenience in distinguishing between different files, we have marked them with uppercase English labels. Please pay attention to the corresponding files at each step. Using incorrect files may result in unexpected on-chain data.

From the outlined steps above, it is evident that project owners do not need to upload each NFT individually to the blockchain. Users are responsible for verifying and bearing the gas costs during the Mint process.

Operation Process

The following operations are based on version 0.1.46 of the atomicals-js command-line tool (@aa34095c). The tool version may be updated periodically, so before proceeding, please check whether your local CLI is the latest or an available version. For installation and configuration, please refer to: https://github.com/atomicals/atomicals-js#install. If you have any questions about a specific command, use -h when entering the command to get help content.

💡 To avoid errors and unexpected discrepancies during the operation, it is recommended to test the entire process on the testnet before any actions on the mainnet.

❗ Each step that includes content with `#container-name` represents the container name, and it must start with `#`. Otherwise, some commands may identify it as a different type of Atomicals.

💰 For each command in the steps with `--satsbyte`, please fill in the value based on the on-chain gas situation.

Prepare Collection Data

1. Prepare a folder containing all the original NFT files (images). It is recommended to pre-change the file names (e.g., "number.png" to "1234.png") to reduce the possibility and complexity of later data modifications. File names only support digits, English, and hyphens (-), and cannot start with a hyphen. The maximum length is 64 characters.

2. Run a command to generate processed data for all NFTs. After completion, a new folder will be generated.

   $ yarn cli prepare-dmint-items "path/to/collection-folder" "path/to/output-folder"
   

3. The generated folder is named "output-folder" with a timestamp, containing individual item-*.json files for each NFT. Please note that the data generated at this point only includes the mainHash and data fields. If necessary, you can specify bitworkc/bitworkr in the args, and after modification, users will be required to use the declared bitwork during minting.

   {
     "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98",
     "data": {
       "args": {
         "request_dmitem": "test-1",
         "main": "image.jpg",
         "i": true
       },
       "image.jpg": {
         "$b": "ffd8ffe000104a4649460001010100600060000ffd9"
       }
     }
   }
   

4. Run the following command to generate DMINT data. Replace path/to/folder with the path to the folder generated in step 2, and mintHeight with the starting block height for minting (a suggested value is 0, meaning minting can occur immediately after deployment). After completion, a new "dmint-timestamp.json" file will be added to the folder, and all processed data for NFTs will be updated.

   yarn cli prepare-dmint "path/to/folder" 0 "b1d0"
   

   {
     "dmint": {
       "v": "1",
       "mint_height": 0,
       "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1",
       "immutable": true,
       "items": 10,
       "rules": [
         {
           "p": ".*",
           "bitworkc": "7baf"
         }
       ]
     }
   }
   

   From here, mint_height can be modified to specify which block your DMINT should start. For example: 840000 means the DMINT of the container can only start after the 840000 height block has been confirmed.

   {
     "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98",
     "data": {
       "args": {
         "request_dmitem": "test-1",
         "main": "image.jpg",
         "i": true,
         "proof": [
           {
             "p": true,
             "d": "3212c74b3b5083433a8111f80369d8c591711c577e45dacb8ccaf7960d96790f"
           }
         ]
       },
       "image.jpg": {
         "$b": "ffd8ffe000104a4649460001010100600060000ffd9"
       }
     },
     "targetVector": "test-1:any:any:image.jpg:0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c97",
     "targethash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98"
   }
   

   ❗ Each time you run prepare-dmint a new dmint-timestamp.json file will be generated, instead of modifying the old one. Please be cautious not to use incorrect data for subsequent operations.

5. You can modify the bitwork rules for dmint. In the rules, p represents the Pattern, allowing you to use regular expressions to specify different bitworkc. Please refer to available resources on regular expressions for rule composition. In the example below, for instance:

   {
     "dmint": {
       "v": "1",
       "mint_height": 0,
       "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1",
       "immutable": true,
       "items": 10,
       "rules": [
         {
           "p": "1$",
           "bitworkc": "890a"
         },
         {
           "p": ".*",
           "bitworkc": "7baf"
         }
       ]
     }
   }
   

See Rules Guide for more details

Warning:** The regex standard being used is the one in Python 3.9. This means that all regex patterns are matched in "full string mode" - meaning that the match is always from the very beginning of a string to the very end even in the absence of ^ or $**

In that case, the rule 1$ signifies that the bitworkc for items ending with 1 (e.g., test1) should be 890a, while other items (e.g., test) should have 7baf as their bitworkc. Rules are ordered from the most specific (minimum subset) to the most general (full set).

❗ If you have individually set bitworkc/bitworkr for an item, you need to manually declare the corresponding pattern and rule in the `rules`. Otherwise, there will be conflicts between them and the base rules, making minting impossible after formal closure and deployment. The tool does not provide any prompts for this, so exercise caution when making modifications.

6. If you modify item data, ensure that you re-run the command from step 4 each time after making changes to regenerate the data.
7. Copy a metadata dmint-metadata.json from template/containers/dmint-collection-general-dmint-metadata.json in the tool directory or https://github.com/atomicals/atomicals-js/blob/master/templates/containers/dmint-collection-general-metadata.json, and adjust it according to your content.

❗ You can refer to the Collection Containers to write this section, but please do not declare `attrs` and `items` as they are incorrect content for DMINT and will lead to the inability to seal the container.

Configure Container

1. ⛓️ Mint the specified container. If you want to specify a different receiving address, replace "yourWalletAddress" with the corresponding wallet address.

$ yarn cli mint-container "#container-name" --initialowner "yourWalletAddress" --satsoutput=1000 --bitworkc="b6cf" --satsbyte=1

2. ⛓️ Enable the dmint status for the container using the previously generated "dmint-timestamp.json." Replace "dmint-json-path.json" with the file path of data B [generated in step 2 - Prepare Collection Data].

❗ You need to wait for 4 block confirmations (turning into verified status) after completing “Configure Container - Step 1”. You can check the container status at https://wizz.cash/live-mint by entering the revealTxid.

$ yarn cli enable-dmint "#container-name" "dmint-json-path.json" --satsbyte=1

3. ⛓️ Upload the resources for the container cover by renaming the file to "logo.png" (preferably in PNG, JPG, or SVG format), then run the following command.

$ yarn run cli store-file "path/of/your_logo.png" "logo.png" --satsbyte=1

......
filesData {
  'logo.png': <Buffer 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00 00 18 00 00 00 18 08 06 00 00 00 e0 77 3d f8 00 00 00 9d 49 44 41 54 78 da 63 60 18 05 54 04 ff ... 164 more bytes>
}
Payload CBOR Size (bytes):  235
Payload Encoded:  {
  'logo.png': <Buffer 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00 00 18 00 00 00 18 08 06 00 00 00 e0 77 3d f8 00 00 00 9d 49 44 41 54 78 da 63 60 18 05 54 04 ff ... 164 more bytes>
}

...
Success sent tx:  f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7af
{
  "success": true,
  "data": {
    "commitTxid": "c931d7a337eef91f5f6f2b3430c78aaac0e7f11752e15576a1a4881b344457c5",
    "revealTxid": "f26bbf1833d6af0ca533cfddbbb1f8074375490120164e6d0a680aca4bacf7af",
    "dataId": "f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7afi0"
  }
}
✨  Done in 81.41s.

After completion, concatenate the filename and the output dataId as: atom:btc:dat:{dataId}/logo.png. Fill in the image field in the metadata file C [generated in step 7 of Prepare Collection Data] with this value.

{
  "name": "container-name",
  "desc": "A test container."
  "image": "atom:btc:dat:1a29d1ed20c36a95f6b5c20977a5f1035cc0cd5f55327692149a5710d1d75e9bi0/logo.png",
  ...
}

4. ⛓️ After modifying metadata C, set it for the container.

$ yarn cli set-container-data "#container-name" "path/to/container-dmint-metadata.json" --satsbyte=1

5. Execute the command to seal the container.

❗ This operation is **IRREVERSIBLE**! Before closing, please complete the item validation in [Validate NFT Item]. Ensure that all items have been validated and are correct.

$ yarn cli seal "#container-name" --satsbyte=1

Validate NFT Item

Due to the uniqueness of Merkle verification, there's no need to upload each NFT in advance. It's sufficient to verify whether they match the container. In different states or lifecycles of the container, you can use various methods to validate the effectiveness of NFT items.

• To validate whether a specific item is effective, you need the container's name, the item's name, and the JSON file generated in step 2 of Prepare Collection Data (replace path/to/item-3.json with the file path of the item).

$ yarn cli validate-container-item "#container-name" "test-item-3" "path/to/item-3.json"

• The result will return the following content. If proof_valid is true, it means the validation is successful. If applicable_rule returns the complete rule, it indicates that the rule configuration is correct:

{
  "success": true,
  "response": {
    "result": {
      "status": null,
      "candidate_atomical_id": null,
      "atomical_id": null,
      "candidates": [],
      "type": "item",
      "applicable_rule": {
        "p": ".*",
        "bitworkc": "a91b"
      },
      "proof_valid": true,
      "target_vector": "test-item-3:any:any:image.jpg:3b0bcfe26b7521e83e595f5838d04ea25a45931a849ab5f0db134eb9a4a7cec2",
      "target_hash": "8d800be8cb6b418d986a99b9d2fd23994fa712f3c76ef9a3c8306298d2af2ba4",
      "dmint": {
        "v": "1",
        "rules": [
          {
            "p": ".*",
            "bitworkc": "a91b"
          }
        ],
        "merkle": "b68ace0edff5f81a92acc57e493d6d3cfa7cfc038bfe0397dfb81d082bd3b9d0",
        "immutable": true,
        "mint_height": 0
      }
    }
  }
}

❗ It is recommended to validate each item to ensure the effectiveness of all data.

Mint NFT Item

After the container is released, users can mint the corresponding NFT using the command-line tool, provided they have access to the json file for the item.

$ yarn cli mint-item "#container-name" "item-name" "path/to/item-name.json" --satsbyte=1

Advanced Topic: Mint Payment Rules

Note: The creator of a DMINT collection can choose to specify that not only is Bitwork required to mint an item, but also certain payments must be made to predetermined addresses in order to finalize the claim process. This is basically purchasing an NFT.

An example rule set with payments defined. Any item ending in "hi" must be claimed with a payment to the output script "5120a1519da5fead1a2e6cc803aedbd79a756f5e0eaafccae641c16e0612fb03071c" with at least 10000 satoshis and every other item claimed must have a payment of 2000 satoshis to "5120a9519da5fead1a2e6cc803acebd79a756f5e0eaafccae641c16e0612fb03072c"

```json
{
  "dmint": {
    "v": "1",
    "items": 1000,
    "rules": [
      {
        "o": {
          "5120a1519da5fead1a2e6cc803aedbd79a756f5e0eaafccae641c16e0612fb03071c": {
            "v": 10000
          }
        },
        "p": "hi$",
        "bitworkc": "888"
      },
      {
        "o": {
          "5120a9519da5fead1a2e6cc803acebd79a756f5e0eaafccae641c16e0612fb03072c": {
            "v": 2000
          }
        },
        "p": ".*",
        "bitworkc": "7777"
      }
    ],
    "merkle": "12e772dc28611968e3f203827ed9c71e0a1e25071032d565b6fb9afee94dd344",
    "immutable": true,
    "mint_height": 0
  }
}
```

In the event that an item minted requires payment, the status of the NFT will indicate that payment is expected for the leading candidate.

Use the `transfer-builder` command to create a custom payment. This is an advanced command and could lead to the loss of funds if used incorrectly.

From the atomical-js CLI:

yarn cli transfer-builder --atomicalreceipt <atomical_id_of_item_claim_attempt> --owner funding --atomicalreceipttype d --satsbyte=80

Then follow the instructions in the terminal to select which UTXOS to combine and send. Make sure you do not send UTXOS with other Atomicals in them. And construct the outputs in a way as to pay the rules defined in the DMINT Container. When in doubt, do NOT use this command, it is risky without advanced knowledge. Wait for 3rd party wallets and services to provide direct payment support.

Optional Operations

The container is already sealed, and users can now begin minting. In the case where some items have already been minted:

Query the status of a single item

get-container-item

$ yarn cli get-container-item "#container-name" "test-item-4"

Query Minted Items

Use get-container-items to query minted items (limit specifies the number of entries, suggested value is 10; offset indicates the starting point for the query, suggested value is 0).

$ yarn cli get-container-items "#container-name" limit offset

description: Overview of Realm Digital Objects (Realm Name Service)

Realm Names

This section describes how to mint a special type of Atomical digital object called a Realm. You can query and search Realm names on https://realm.name

-> What is a Realm?

Realm Names are human-readable identifiers which can be used to associate network addresses and resource information. A Realm name begins with the plus + sign and has at least one alphabetical character, such as +alice and +agent007 which are both valid names (top-level-realms or TLRs) in the Realm Name System (RNS). Realm names are self-owned and self-managed directly on the Bitcoin blockchain using the Atomicals Digital Object format — which basically means that there is no middle man or centralized registrar. Once you claim a name, it's yours forever or until you transfer it to someone else.

Mint Realm

Before using the commands below you must first create a local wallet using the wallet-init command. For convenience the commands.

Step 1. Download and Install atomicals-js CLI

Download and install the atomicals-js CLI.

git clone https://github.com/atomicals/atomicals-js.git
cd atomicals-js
yarn install
yarn build

Step 2. Wallet Initialize

The purpose of the wallet is to create p2tr (pay-to-taproot) spend scripts and to receive change from the transactions made for the various operations. Do not put more funds than you can afford to lose, as this is still beta!

To initialize a new wallet.json file that will store your address for receiving change use the wallet-init command.

yarn cli wallet-init

>>>

Wallet created at wallet.json
phrase: maple maple maple maple maple maple maple maple maple maple maple maple
Legacy address (for change): 1FXL2CJ9nAC...u3e9Evdsa2pKrPhkag
Derive Path: m/44'/0'/0'/0/0
WIF: L5Sa65gNR6QsBjqK.....r6o4YzcqNRnJ1p4a6GPxqQQ
------------------------------------------------------

Step 3. Mint Realm

The basic format to mint a Realm name using the Atomicals CLI is:

yarn cli mint-realm "myrealmname"

Optional flags:
--satsbyte=<number>

The realm mint function mint-realm allows minting for Realm myrealmname as long as you are the first to claim it.

Follow the on-screen instructions to pay and mint.

Required Parameters:

realmname: The globally unique realm name

Optional Flags:

--satsbyte=<number>

Set the satoshis per byte for the transaction and override the default.

Step 4. Query Realm name

You must wait 3 confirmations for the name to be claimed and registered correctly. After it is claimed, you can query the realm name with the command:

yarn cli get +myrealmname

You may also query and search Realm names on https://realm.name

Step 5. Query global feed (optional)

You can query the global feed of registered Realms and Atomicals:

yarn cli list

\

description: >- Send and receive crypto with human readable payment names powered by the Atomicals Realms Protocol.

Payname Format

Format Convention

+[inbox]@[realm_name]

Where:
+ is always required at the front to denote it is a Realm user recipient

inbox: The name of the inbox associated with the Realm payment name

@ is required to indicate the inbox is located at the Realm

realm_name: The fully qualified Realm or Subrealm name

Examples

+hello@samplerealm
+main@samplerealm
+support@samplerealm

Note: The inbox can be data representing the cryptocurrencies or payment methods accepted there, it can also be configured to delegate to another NFT to handle the data updates.

On-Chain Data Object Format

To see how to store the data for a Realm, consider the following format layout for a Realm/NFT.

{
  "paynames": {
    "delegate": "atom:btc:id:<atomical_id>/paynames",
    "hello": {
      "delegate": "atom:btc:id:<atomical_id>/paynames/hello"
    },
    "main": {
      "types": {
         "btc": {
           "value": "bitcoin btc address"
         },
         "ltc": {
           "value": "litecoin ltc address",
           "notes": "optional notes",
           "instructions": "optional instructions"
         }
      }
    }
  }
}

Fields

paynames: The top level field that will store the paynames settings and configuration data for the Realm, which can contain additional keys which will identify the inboxes. Only characters /a-z0-9\./ should be considered valid. Maximum 64 character names.

types: The tickers for the various cryptocurrencies and payment types accepted

delegate: It is possible to delegate the entire pay names available for a Realm to an NFT, and it is also possible to delegate an individual inbox. When delegate is set at the top directly underneath paynames field, then it takes precedence and the rest of the data is ignored (since the entire paynames settings are delegated elsewhere)

description: >- Every Realm and Sub-Realm has the ability to mint any number of Sub-Realms below them.

Mint Sub-Realms

Method 1: Mint with Sub-Realm Rules

The first way to allow users to mint subrealms is to define the minting rules at the subrealms namespace in the Realm or Subrealm data structure. We will demonstrate below how to configure a realm (or subrealm) to allow users to mint subrealms autonomously. We start with the sample realm name +mycoolrealm and walk through the steps required to enable subrealm minting.

Pre-Requisites

• You have a Realm or Sub-Realm already claimed
• Decide how you will allow user's to mint subrealms (more on this below)

Step 1. Create initial Subrealm Minting Rules File

See Rules Guide for more details for more details on the format of the rules file. Below we will demonstrate how to configure a sample rules configuration for our example Realm +mycoolrealm

The example demo Realm+mycoolrealm exists on testnet at atomical_id285051d51bb9d045d24dc0816d6f29bfe72b1c91e479702ec866c724a0f4aa56i0

Sample Rules File (Save as rules.json)

```json
{
  "subrealms": {
    "rules": [
        {
          "p": "^[a-z0-9]{6,64}$",
          "bitworkc": "8888.8"
        },
        {
          "p": ".*",
           "o": {
            "0014383fb23c5b1b40025b0e1dd3e310d6e1ee6d316e": {
              "v": 1000
            }
          }
        }
    ]
  }
}
```

The rules file above allows anyone to mint a subrealm of length 6 to 64 characters in length for free as long as the user mines the Subrealm with Bitwork of "bitworkc": "8888.8" (about 1-2 minutes of CPU time). There is a second additional rule entry that allows subrealms to be minted less than 6 characters in length as long as a payment of 10,000 satoshis is made to the address.

Recall that you can convert between output script hex format to addresses and vice versa using the CLI tool. See Rules Guide for more details.

Step 2. Set the Minting Rules with "enable-subrealms" for your Realm

With the rules file you have created above in Step 1, we will enable it for your particular Realm.

Using the CLI, execute the following command to enable subrealm minting:

yarn cli enable-subrealms +mycoolrealm file.json --satsbyte=100

Then follow the on-screen instructions to deposit the funds into your funding address, and after the transaction is confirmed your rules will become activated and anyone can mint subrealms according to the rules you have created.

Step 3. Query "realm-info" to see activated rules

After the transaction in Step 2. is completed successfully and confirmed in at least 1 block, then you may query the activated rules for your realm with the command:

yarn cli realm-info mycoolrealm

It will display the relevant information about the Realm and the activated rules.

⭐ Congratulations! You have successfully enabled Subrealm Minting on your Realm or Subrealms. Read below on how your users can participate and claim subrealms

Mint and Claim Subrealm

To mint and claim a subrealm according to the rules created above, the users can use the following commands to query if a Subrealm name is available, and determine the minting rules that are applicable and check the status of their request.

Step 1. Query the Subrealm to claim to check if is available

Query the subrealm +mycoolrealm.nicesubrealm to see if it is available and if it's taken. The command realm-info like the DNS WHOIS command to report back information about a realm name.

yarn cli realm-info mycoolrealm.nicesubrealm

Step 2. Mint the Subrealm Request

yarn cli mint-subrealm +mycoolrealm.nicesubrealm --satsbyte=100

Then follow the on-screen instructions. In the case of a mint that requires a payment, then you must use a tool that allows payments.

Step 3. (If payment is required) Make payment for Subrealm during payment window.

The CLI has the operation to see which Subrealms are ready to be paid and also help pay with regular Satoshis:

yarn cli pending-subrealms 

Then follow the on-screen instructions to make regular Satoshi payments.

⚠️ WARNING: It is not recommended to use the CLI to make payments for high value items and/or paying with ARC20. The tool is experimental and it is not advised to use the tool unless you are an advanced user. It is better to use one of the upcoming wallets to handle the payment complexity on your behalf.

description: Overview of the Rules system for claiming Subrealms and DMINT

Rules (Subrealms & DMINT)

Subrealms and NFT items (with DMINT - Decentralized Mints) can be minted (or "claimed") according to the rules set up by the owner of the parent realm or in in the case of DMINT, the creator of the container.

It is possible to pay for a subrealm or DMINT'ed item using only proof of work (Bitwork) and/or also paying any set of output addresses a certain amount of Satoshis or value in an ARC20 token.

Format of Rules Data-structure

The rules section in the dmint (for containers) and subrealms section for Realms is identical and has the same syntax and semantics.

We demonstrate the use of the rules, by building upon simple examples and gradually increasing complexity.

Warning: The regex standard being used is the one in Python 3.9. This means that all regex patterns are matched in "full string mode" - meaning that the match is always from the very beginning of a string to the very end even in the absence of ^ or $

Example 1: Require only Bitworkc mining to claim mint

Require the use of Bitwork to mine on the commit transaction (bitworkc). The pattern "p": ".*" means to match any subrealm name or any dmint item id, then the only form of "payment" required is that the item must be minted with "bitworkc": "1234" on the commit transaction to claim.

```json
{
  "rules": [
      {
        "p": ".*",
        "bitworkc": "1234"
      }
  ]
}
```

Example 2: Require both Bitworkc and Bitworkr mining to claim mint

Require the use of Bitwork to mine on the commit transaction (bitworkc). The pattern "p": ".*" means to match any subrealm name or any dmint item id, then the form of "payment" required is that the item must be minted with "bitworkc": "1234" on the commit transaction to claim. Additionally the reveal transaction must have "bitworkr": "8888.10" which means it must match "8888.*" for the transaction hash as long as the 5th hex character is greater than or equal to "a" (10 in hex).

```json
{
  "rules": [
      {
        "p": ".*",
        "bitworkc": "1234",
        "bitworkr": "8888.10"
      }
  ]
}
```

Example 3: Require different Bitworkc based on the name of the item

In the third example, we specify that if the item name starts with the number "0" or the name ends in .gif then the Bitwork required is about 16x harder (ie: 16x more CPU/GPU mining will be required)

```json
{
  "rules": [
      {
        "p": "^0|\.gif$",
        "bitworkc": "77777"
      },
      {
        "p": ".*",
        "bitworkc": "7777"
      }
  ]
}
```

Example 4: Require a payment to a certain address to claim the item

To enable "pay to claim" use the "o" (output script) field to indicate what output must be paid in order to successfully claim.

```json
{
  "rules": [
      {
        "p": ".*",
         "o": {
          "5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4": {
            "v": 1000
          }
        },
      }
  ]
}
```

The above means that the output script of 5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4 must be paid at least "v": 1000 satoshis for the claim to succeed. The script decodes to address bc1p49mrdne5j2j5dktkupflvx6s0z8027ssk2yg2f6mvzand8nzjrjqschm45

Note: Use the CLI utility commands "yarn cli script-address <script>" to get the address decoded. To perform the reverse and get the script for an address use "yarn cli address-script <address>"

The reason for the use of the hex encoded output script is because a project may want the user to post a message in the form of an OP_RETURN on the blockchain instead of payment. Additionally it is more flexible for future address types.

Example 5: Require a payment to multiple address to claim an item

To enable "pay to claim" use the "o" (output script) field to indicate what outputs must be paid in order to successfully claim. In the example below in order to claim the items that start with "000\d" (ie: items 0000 to 0009") they must pay 5000 satoshis to output script 5120bd5ba4e806e8cf69eff55af83c9b910f82d1978bfac53ce48554ce291dd22bec (address: bc1ph4d6f6qxar8knml4tturexu3p7pdr9utltzneey92n8zj8wj90kqshxyqa) and also at the same time pay output script 5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4 (address: bc1p49mrdne5j2j5dktkupflvx6s0z8027ssk2yg2f6mvzand8nzjrjqschm45) 1000 satoshis.

```json
{
  "rules": [
      {
        "p": "^000\d$",
         "o": {
          "5120bd5ba4e806e8cf69eff55af83c9b910f82d1978bfac53ce48554ce291dd22bec": {
            "v": 5000
          }
        },
        "p": ".*",
         "o": {
          "5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4": {
            "v": 1000
          }
        }
      }
  ]
}
```

Example 5: Require a payment with specific ARC20 token to claim an item

To enable "pay to claim" use the "o" (output script) field to indicate what outputs must be paid in order to successfully claim. In the example below in order to claim the items that start with "000\d" (ie: items 0000 to 0009") they must pay output script 5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4 (address: bc1p49mrdne5j2j5dktkupflvx6s0z8027ssk2yg2f6mvzand8nzjrjqschm45) with 1000 units of the ARC20 token identified by id 2112003789d572f764ff91b273266997e3a1153e017dc8a4fca020eaff324301i0

```json
{
  "rules": [
      {
        "p": ".*",
         "o": {
          "5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4": {
            "id": "2112003789d572f764ff91b273266997e3a1153e017dc8a4fca020eaff324301i0",
            "v": 1000
          }
        }
      }
  ]
}
```

Example 6: Require Bitworkc mining and a payment with specific ARC20 token to claim an item

The example below combines Examples above to also require Bitworkc (commit txid) mining and also a payment of a specific token

```json
{
  "rules": [
      {
        "p": ".*",
         "o": {
          "5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4": {
            "id": "2112003789d572f764ff91b273266997e3a1153e017dc8a4fca020eaff324301i0",
            "v": 1000
          }
        },
        "bitworkc": "7878"
      }
  ]
}
```

When to make a Payment after the initial claim candidate

When a payment rule includes a requirement to pay at least one address, then the user who minted the claim must wait 4 block confirmations to ensure they are the leading candidate to win the subrealm or item. Then they have an additional 11 block confirmations to make the payment according to the payment rules and must attach an OP_RETURN receipt which specifies which atomical id they are claiming and paying for.

The reason for this 2 step process is that if it was not 2 steps, then a malicious NFT collection could front run valid payments and then cheat users out of their items by paying faster than the user. Therefore we use the candidate system to ensure only 1 user has the leading candidate and the eligibility to make the payment. If the user does not complete the payment and confirmed on the blockchain within 15 blocks since their original commit transaction, then another user can take the candidate lead and issue their payment and be awarded the item.

We strongly recommend wallet and service implementors use a fee rate that is at least 50% to 100% higher than the prevaling Bitcoin network conditions to ensure the payment arrives on time and not delayed after ther 15 block confirmations

description: Proof of Work CPU/GPU Mineable Tokens

Bitwork Mining

Atomicals introduces GPU Mineable Tokens that demonstrates proof of work and energy burn. It is now possible to create provably rare and hard-to-find tokens. Easily encode an arbitrary string such as "hello" (In hex: "68656C6C6F") and have it be a requirement in the transaction id of the NFT or even to create a validate decentralized mint in the ARC-20 fungible token protocol.

In our example, to encode "hello" we require 16^10 ~ approximately 1.1 trillion hashes to generate. That would take approximately 10 to 20 minutes on a modern GPU to generate (assuming 1 billion hashes per second). Initially and more practically, one can simple require a smaller prefix such as "21e8" or "7777" which would require only 16^4 ~ 65,000 hashes and easily achievable on desktop computers and smartphones. This is enough to throttle spammers and provide contextual data information encoded right there in the transaction id.

Taking the step further, it is now possible to create an unstoppable content ranking algorithm for upvoting NFTs, tokens, and posts. The Atomicals indexer automatically indexes and categories all proof of work for Atomicals Digital objects and arbitrary "dat" (simple data transactions) into a proof of work content rank index. This allows a never before possible way to rank social media posts that will elevate highly energized content in a way that cannot be merely bought by the highest bidder (without running out of energy!)

The proof of work token mining system will solves the problem of content discovery, ranking and spam filtering. It will now be possible upvote content in marketplaces and NFT platforms and know for certainty that the rank was not manipulated or merely sold to the highest bidder. Welcome to the future.

The ARC-20 token standard follows in the footsteps of BRC-20, and also has the option to require proof of work before awarding tokens for the decentralized mints. This allows the initial token ticker deployer to define how much energy burn must be expended before awarding the token the minters. And it makes for a very beautiful mint pattern -- because all initial supply will be minted from transaction ids that share the same common prefix such as "e7ee7" or "010101" or "21e8", etc...

Atomicals introduces a novel way to mine proof of work vanity prefixes into token transaction ids.

Fine Tuning Proof of Work Bitwork Prefix

You may also include a number from 1-15 after the prefix such as: '7777.1' or "7777.15" or anything in between. The number represents the allowable variations for that digit.

The way it works is that the digit after the dot "." is interpretted as a semi wild card to match any of the 5th character starting from that number.

Take "7777.10" as an example: The first 4 txid hex chars must match "7777" and the 5th character must match the 10th hex digit and up only. The 5th digit is allowed to be a, b, c, d, e, or f

0
1
2
3
4
5
6
7
8
9
a
b
c
d
e
f

What this system allows is fine tuning and so we are not restricted to increasing the difficulty each time by 16x, but instead can chose a range between 2x to 16.

description: >- Create hierarchies and includes of Atomicals digital objects with recursion and references

Recursion and References

The following URNs are defined to simplify including and referencing different Atomicals resources.

NOTE: When referring to references in an Atomical, it is recommended to. use the ctx top level field in the data to import or include references to other Atomicals and data files. The ctx top level is reserved specially for this reason.

Examples of Recursion with References in the ctx field:

{
  // Any Atomical data above...
  "ctx": {
     // Implied to always get the latest data for an atomical:
     "resourcename": "atom:btc:id:<atomical_id>/mydata",
     // Gets permanent data file image.png at the dat_id
     "icon": "atom:btc:dat:<dat_id>/image.png",
     // Gets the minted "name" property for a collection
     "collection-name": "atom:btc:container:<dat_id>$name",
     // Gets the latest version of import.js located at a realm name
     "assetbuilder.js": "atom:btc:realm:<realm_name>/import.js",
  },
  // Another other Atomical data ...
}

Note: It is preferably to use the "dat" command to refer to on-chain assets where applicable. When using containers, realms or the dynamic references (using slash "/") it is possible the resource.

Conventions

The convention is to use the prefix "atom:btc" to indicate the Atomicals Protocol on the Bitcoin (BTC) network. It is possible to reference digital objects by atomical_id, container name, or (sub)realms and immutable file data by the data_id.

The basic form of the Atomicals Universal Resource Name (URN) is:

atom:<chain>:<ref_type>:<identifier>[$ or /[<file>]]

Where:

chain: The referenced blockchain, set to "BTC" for Bitcoin

ref_type: The type of reference. Currently supported "id", "container", "realm", and "dat"

identifier: The identifier corresponding to the ref_type. Such as atomical_id, container name, realm name, or the reveal location of the immutable data in the case of "dat"

$ or /: Whether to refer to the mint (original) data (using dollar sign $)orthedynamic(latest)data(usingslash/)ofafileforanAtomical.Youwillnoticethatforthe‘dat‘ref\_typeeither$ or / is acceptable and will return the same data regardless.

file: The name of the file is optional, if omitted then general information about the resource is returned

The philosophy is that we should be able to unambiguously reference Atomicals digital objects based on their types. At the base level every type such as container and realm can also be referenced by the atomical_id. Furthermore, we should always be able to get the original mint data, and also get the latest version of files stored, including every revision of that file either by txid, version number, or block height.

References by Atomical ID

Get general information

atom:btc:id:<atomical_id>

Ex: atom:btc:id:14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0

Get original minted data as JSON

atom:btc:id:<atomical_id>$

Get original minted file

atom:btc:id:<atomical_id>$links

atom:btc:id:<atomical_id>$info.pdf

Get latest dynamic data state

atom:btc:id:<atomical_id>/

Get latest version of a file

atom:btc:id:<atomical_id>/image.png

Get specific version of a file

atom:btc:id:<atomical_id>/image.png@[txid or version number or blockheight]

The [txid or version number or blockheight] can be of the form:

• hexadecimal of the txid that was one of the valid updates to the file
• Version number starting with "v" such as "v1"
• Block height for the state of the file as of that block height

References by Container Name

Get general information

atom:btc:container:<containerName>

Examples:
atom:btc:id:my-coolcontainer-name

Get original minted data

atom:btc:container:<containerName>$

Get latest dynamic data state

atom:btc:container:<containerName>/

Get original minted file

atom:btc:container:<containerName>$image.jpg

Get latest version of a file

atom:btc:container:<containerName>/items

Get specific version of a file

atom:btc:container:<containerName>/items@[txid or version number]

References by Realms

Get general information

atom:btc:realm:<realmName>

Where realmName can be a Top Realm or any Sub Realm

Examples:
atom:btc:realm:myrealm
atom:btc:realm:myrealm.somesubrealm
atom:btc:realm:myrealm.somesubrealm.thirdlevel-subrealm

Get latest version of a file

atom:btc:realm:<realmName>/profile

Get specific version of a file

atom:btc:realm:<realmName>/profile@[txid or version number]

The [txid or version number or blockheight] can be of the form:

• hexadecimal of the txid that was one of the valid updates to the file
• Version number starting with "v" such as "v1"
• Block height for the state of the file as of that block height

References by ARC20 (Fungible Tokens)

Get general information

atom:btc:arc:<ticker>

Where ticker can be a ticker name of an ARC20 token

Get mint original data

atom:btc:arc:<ticker>$

atom:btc:arc:<ticker>/icon.png

Get event feed at ticker

atom:btc:arc:<ticker>/events (To be determined - TBD)

References to Immutable Data

To store immutable (non digital object data) use the "dat" command (store-file) and reference it using the dat URN of the form:

atom:btc:dat:<data_id>/image.png

Notice that the dat immutable data storage can use either the $ or the / since there is only one version of the immutable data and both will return the same data.

description: >- Store files and data immutably for the scenarios when it's not needed to create a dynamic Atomical Digital Object

Permanent File Storage

Example: Storing Immutable Image File on Chain

Using the command line utility, execute the following command to set the data for a sample image file. Use the store-file command line (dat operation on chain) to specify the path to the file and the on-chain filename ("image.png" is the desired target name in the example below)

// immutably store an image on-chain to reference in the container metadata
yarn cli store-file ./path/to/image.png image.png --satsbyte=10

Success sent tx:  db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f
{
  "success": true,
  "data": {
    "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997",
    "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f",
    "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0"
  }
}

We will use the reveal location (db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0) to refer to the image image.png below.

Now that the file is on chain, use the recursion and references URN syntax to refer to the file.

description: >- Theory of Operations of how names, tickers and other assets are claimed First is First.

First is First Candidate System

Coming soon....

description: Frequently Asked Questions About The Atomicals Protocol

FAQ

What is the Atomicals Protocol?

Atomicals Protocol is the most simple, flexible and secure way of creating digital objects on Bitcoin. Every Atomical is a self-evident and tamper resistant chain of digital signatures, it is a robust file format for every use imaginable. Everything on the internet can now potentially be owned digital property.

Does Atomicals require a separate chain, additional layers or any changes to Bitcoin?

No! It's here now and works on native Bitcoin and existing wallets today. It leverages the key design of Bitcoin and requires no secondary layers, side-chains and no trusted services to operate.

What can Atomicals Digital Objects be used for?

Atomicals is designed for the most demanding security requirements with zero room for error. Digital Objects perfect for everything from digital art, authentication schemes to virtual land and title registries and social media such as:

• Digital collectibles, media and art
• Digital identity, authentication and token-gated content
• Web hosting and file storage
• Peer to peer exchange and atomic swaps
• Digital namespace allocation
• Virtual land and title registries
• Dynamic objects and state for games
• Social media profiles, posts and communities

The heart of Atomicals is a few key simple rules to follow for mint, transfer, and update operations, continue reading to the Protocol Overview to understand the high level flow before diving deeper. If you like, you can just skip all the theory and go straight to minting your first Atomical within a couple of minutes.

How does Atomicals Protocol work?

Learn more about how the protocol works by visiting the Protocol Specification page.

{% include "reference-and-tools/specification.md" %}

Why are Atomicals called "digital objects" instead of "NFTs"?

A non-fungible token (NFT) is a highly technical term that does not convey the diverse set of usages available. Atomicals uses the term "digital objects" to elicit all of the potential uses of the protocol. It is far more familiar to the average person and is also very developer friendly in the sense that we already work with digital objects and understand their properties.

description: Detailed Documentation of Atomicals Protocol

Specification

The heart of Atomicals Protocol is a few simple rules to follow for mint, transfer, update, delete and extract operations. After getting acquainted with the theory, jump to minting your first Atomical Digital Object in a few minutes

⚠️Warning: The specification is defined in code. Review the commands in the atomicals-js CLI to see how they function accurately.

Envelope

All methods follows a "commit and reveal" scheme leveraging Taproot (P2TR) spend path scripts. In the witness script for an input, we put the Atomicals envelope which will contain the various operations that can be legally performed on an Atomical.

The convention is to use an OP_FALSE OP_IF ... OP_ENDIF to place arbitrary non-executable content in a witness spend script. We use the bytes of "atom" (61746F6D in hex) to indicate this envelope belongs to the Atomicals Protocol.

OP_FALSE
OP_IF
 0x0461746F6D // Push "atom" 4 bytes
 <Operation>  // Followed by a single push to denote the operation type
 <Payload>    // Payload (CBOR encoded) for the operation
OP_ENDIF

The envelope can appear anywhere in the spend script, but it is recommended to put it after a pay-to-pubkey-hash (p2pkh), which would actually be:

<pubkey-hash>
OP_CHECKSIG     // Perform a check signature against the pubkey-hash
OP_FALSE
OP_IF
 0x0461746F6D // Push "atom" 4 bytes
 <Operation>  // Followed by a single push to denote the operation type
 <Payload>    // Payload (CBOR encoded) for the operation
OP_ENDIF

The format of the <Operation> field is a single push data representing the type of operation that follows. The <Payload> data is interpreted in the context of the operation type. The <Payload> is a CBOR encoded data structure and can be decoded in a variety of programming languages. CBOR provides a concise and expressive way to encode data and greatly simplifies parsing Atomicals protocol operations since there are only push datas that contain the necessary information for all the files and their metadata.

Payload Format Description

The payload format is intuitive and simple: Each top-level field is a file (or field) name and below it can be any valid JSON-like structure. In the case that there is a "ct" (content-type) field in the payload, then it is interpreted to be a file of that type with the bytes located at "d"

The payload is CBOR encoded and can be of any size in a single push data up to 520 bytes. If the payload is larger, then include subsequent push datas of size 520. It is understood that parsers will concatenate all chunks together and then perform a CBOR decode to obtain the data structure.

If any point the payload is not CBOR encoded compliant, then it is assumed there is no data associated the NFT. The absence of a Payload field is valid, but also merely indicates there is no data. Some digital objects may not have explicit payload data as part of their mint event.

A final note is that any field with a sub-key "ct" (content-type) is assumed to be a file if and only if the "d" bytes are also provided. If they are not provided, then the field is treated as a non-file metadata field.

Sample Payload Format

  {
    "someimage.png": "binary data",
    "meta": {
      "some": "value",
      "another: {
        "fieldabc": 123
      }
    },
    "args": {
      "r": "abc"
    }
  }

description: Learn about the Decentralized Atomicals ElectrumX Index Service

ElectrumX API

Open The Atomicals ElectrumX API Documentation

description: >- Interact with Atomicals using the Command Line Interface (CLI) Javascript Library

Javascript Library (CLI)

Get the Command Line Interface (CLI) from Github:

Atomicals GitHub Repository