├── .github └── workflows │ └── gh-pages.yml ├── .gitignore ├── README.md ├── SUMMARY.md ├── arc20-tokens ├── README.md ├── normal-transfer-rules.md ├── substantiation-factor.md └── swap-transfer-rules.md ├── assets ├── Transfers of Fungible Tokens (ARC20) (1) (1).png ├── Transfers of Fungible Tokens (ARC20) (1).jpg ├── Transfers of Fungible Tokens (ARC20) (1).png ├── Transfers of Fungible Tokens (ARC20) (10).jpg ├── Transfers of Fungible Tokens (ARC20) (14) (1).jpg ├── Transfers of Fungible Tokens (ARC20) (14).jpg ├── Transfers of Fungible Tokens (ARC20) (15).jpg ├── Transfers of Fungible Tokens (ARC20) (16).jpg ├── Transfers of Fungible Tokens (ARC20) (2) (1).png ├── Transfers of Fungible Tokens (ARC20) (2).jpg ├── Transfers of Fungible Tokens (ARC20) (2).png ├── Transfers of Fungible Tokens (ARC20) (3).png ├── Transfers of Fungible Tokens (ARC20) (4).jpg ├── Transfers of Fungible Tokens (ARC20) (5).jpg ├── Transfers of Fungible Tokens (ARC20) (6).jpg ├── Transfers of Fungible Tokens (ARC20) (7).jpg ├── Transfers of Fungible Tokens (ARC20) (8).jpg ├── Transfers of Fungible Tokens (ARC20) (9).jpg ├── Transfers of Fungible Tokens (ARC20) Insuff.png ├── Transfers of Fungible Tokens (ARC20) base 1.png ├── Transfers of Fungible Tokens (ARC20) over.png ├── Transfers of Fungible Tokens (ARC20) swap1.png ├── Transfers of Fungible Tokens (ARC20).jpg ├── Transfers of Fungible Tokens (ARC20).png ├── WhatsApp Image 2023-12-12 at 9.35.07 AM (1).jpeg ├── WhatsApp Image 2023-12-12 at 9.35.07 AM (2).jpeg ├── WhatsApp Image 2023-12-12 at 9.35.07 AM.jpeg ├── WhatsApp Image 2023-12-12 at 9.35.08 AM (1).jpeg ├── WhatsApp Image 2023-12-12 at 9.35.08 AM.jpeg ├── arqr (1).png ├── arqr.png ├── atomblack.jpg ├── atomicals black.png ├── atomicals drawings (2).jpg ├── atomicals drawings.jpg ├── atomicalsbanner.png ├── banner (1).png ├── banner.png ├── banner2.png ├── bannercover.png ├── bc1pa5hvv3w3wjwfktd63zcng6yeccxg9aa90e34n9jrjw3thgc52reqxw6has.png ├── burn.jpeg ├── delete.jpeg ├── extract.jpeg ├── merge mixed.jpg ├── newer.png ├── qrcode1.png ├── qrcode2.png ├── qrcode3.png ├── rescale.jpg ├── rescaledust.jpg ├── split mixed.jpg ├── split st start.jpg ├── transfer.jpeg ├── transferrules.jpeg └── update.jpeg ├── bitwork-mining.md ├── book.toml ├── collection-containers ├── README.md └── dmint-guide.md ├── faq.md ├── first-is-first-candidate-system.md ├── nfts ├── README.md ├── normal-transfer-rules.md ├── splat-operation.md └── swap-transfer-rules.md ├── permanent-file-storage.md ├── realm-names ├── README.md ├── mint-sub-realms.md └── payname-format.md ├── recursion-and-references.md ├── reference-and-tools ├── electrumx-api.md ├── javascript-library-cli.md └── specification.md └── rules-subrealms-and-dmint.md /.github/workflows/gh-pages.yml: -------------------------------------------------------------------------------- 1 | name: 'Publish to GitHub Pages' 2 | 3 | on: 4 | workflow_dispatch: 5 | push: 6 | branches: 7 | - main 8 | 9 | jobs: 10 | build: 11 | runs-on: ubuntu-latest 12 | concurrency: 13 | group: ${{ github.workflow }}-${{ github.ref }} 14 | steps: 15 | - uses: actions/checkout@v2 16 | - name: Setup mdBook 17 | uses: peaceiris/actions-mdbook@v2 18 | with: 19 | mdbook-version: 'latest' 20 | - run: cargo install mdbook mdbook-katex 21 | - run: mdbook build 22 | - name: Deploy 23 | uses: peaceiris/actions-gh-pages@v3 24 | with: 25 | github_token: ${{ secrets.DEPLOY_TOKEN }} 26 | publish_dir: ./book 27 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | .vscode/ 3 | 4 | ## Dependency directory 5 | ## Commenting this out is preferred by some people, see 6 | ## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git 7 | node_modules 8 | 9 | # Book build output 10 | _book 11 | book 12 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 |

Atomicals Protocol brings Digital Objects to life on Bitcoin and proof-of-work based blockchains.

4 | 5 | ## What is the Atomicals Protocol? 6 | 7 | The Atomicals Protocol is a simple, yet flexible protocol for minting, transferring and updating 8 | _digital objects (traditionally called non-fungible tokens)_ 9 | for unspent transaction output (UTXO) blockchains such as Bitcoin. An Atomical (or "atom") is a way to organize the creation, 10 | transfer and updates of digital objects – it is essentially a chain of digital ownership defined according to a few simple rules. 11 | 12 | ## Why use Atomicals? 13 | 14 | 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. 15 | 16 | ## Use Cases 17 | 18 | * Digital collectibles, media and art 19 | * Digital identity, authentication and token- gated content. 20 | * Web hosting and file storage 21 | * Peer to peer exchange and atomic swaps 22 | * Digital namespace allocation 23 | * Virtual land and title registries 24 | * Dynamic objects and state for games 25 | * Social media profiles, posts and communities 26 | * Anywhere security and decentralization is critical concern. Military grade security and verification requirements. 27 | 28 | 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. 29 | 30 | The motto is: 31 | 32 | **"No transaction history, not your digital object"** 33 | 34 | 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. 35 | 36 | 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.](reference-and-tools/javascript-library-cli.md) 37 | 38 | ## What are Atomicals Digital Objects? 39 | 40 | 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.** 41 | 42 | 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. 43 | 44 | 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. 45 | 46 | ## The Atomicals Vision 47 | 48 | \ 49 | 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. 50 | 51 | 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.\ 52 | \ 53 | 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.\ 54 | \ 55 | It is designed to work in harmony with the other protocols that have emerged such as [Nostr](https://nostr.com), [Ordinals](https://ordinals.com) 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.\ 56 | \ 57 | 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. 58 | 59 | ## Key Differences From Other Protocols 60 | 61 | The best way to understand the differences of Atomicals is to compare it against other popular non-fungible token (NFT) protocols. 62 | 63 | | | Atomicals | Ordinals | Ethereum ERC721 | 64 | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| 65 | | **Value Proposition** | Digital Objects | Digital Artifacts | Digital Collectibles | 66 | | **Blockchains** | Bitcoin and all UTXO blockchains | Bitcoin and all UTXO blockchains | Ethereum EVM compatible blockchains | 67 | | **Mint Technique** | Bitcoin: Commit & reveal w/ "_atom_" envelope. | Bitcoin: Commit & reveal w/ "_ord_" envelope. | Fund and deploy contract account | 68 | | **Data Storage** | Store _one or multiple_ files upon minting | Store only one file upon minting | _Not defined_ | 69 | | **Dynamic State** | Define _and update app state_ for basic and any complex file types | _Not defined_ - can be defined on app specific basis | _Not defined -_ can be programmed up front | 70 | | **Validation** | Validation currently through the indexing service "electrumx" - in theory it's possible to validate 100% client-side. | Validation currently through the indexing service "ord" - in theory it's possible to validate 100% client-side. | Trusts Ethereum EVM nodes or in practice trust Metamask or Infura | 71 | | **Indexing** | Validation relies on elecrumx atomicals indexer (Python) at the moment for tracking ordinal numbering system. | Validation relies on _ord_ indexer (Rust) at the moment for tracking ordinal numbering system. | Uses native Ethereum EVM nodes or in practice trust Metamask or Infura | 72 | | **Address Format** | P2TR (Taproot) addresses required for mint and updates. | P2TR (Taproot) addresses are required for all uses such as mint and transfers | Uses native Ethereum Account address. | 73 | | **Collections** | First-class "Container" NFT for updating collections, sealable permanently. | Not defined but is in progress with parent-child relationships | Defined as separate ERC | 74 | | **Atomics Swaps** | Partially Signed Bitcoin Transactions (PBSTs) | Partially Signed Bitcoin Transactions (PBSTs) | Defined as separate ERC | 75 | | **Fungible Tokens** | First-class "ARC20" using Satoshis as unit of account. Decentralized and direct minting modes available. Built-in ticker name service | Not provided in base protocol. "BRC20" creates a JSON protocol in an Inscription to define the decentralized mint rules and ticker name. | Defined as ERC20 type tokens | 76 | | **Name Service** | Realms are first-class NFTs that represent domain names and digital identities. A new naming standard with no domain suffix, starts with plus "+" sign like +username | Not provided in base protocol. ".names" and ".sats" protocols exist as JSON protocol in an Inscription to define the claim and update rules. | Existing services such as ENS and Unstoppable Domains | 77 | 78 | ## Atomical Numbers, IDs, REFs 79 | 80 | 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. 81 | 82 | 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 _**\**_**i**_**\**_ (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. 83 | 84 | 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') 85 | 86 | ## Get Started and Create Your First Atomical Digital Object 87 | 88 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and mint your first Atomical in less than 2 minutes. 89 | 90 | 91 | 92 | 93 | 94 |
95 | 96 | ⚡ Get started and mint your first Atomical Digital Object 97 | 98 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 99 | 100 |
101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [Introduction](README.md) 4 | 5 | * [NFTs](nfts/README.md) 6 | * [Normal Transfer Rules](nfts/normal-transfer-rules.md) 7 | * [Swap Transfer Rules](nfts/swap-transfer-rules.md) 8 | * [Splat Operation](nfts/splat-operation.md) 9 | * [ARC20 Tokens](arc20-tokens/README.md) 10 | * [Normal Transfer Rules](arc20-tokens/normal-transfer-rules.md) 11 | * [Swap Transfer Rules](arc20-tokens/swap-transfer-rules.md) 12 | * [Substantiation Factor](arc20-tokens/substantiation-factor.md) 13 | * [Collection Containers](collection-containers/README.md) 14 | * [DMINT Guide](collection-containers/dmint-guide.md) 15 | * [Realm Names](realm-names/README.md) 16 | * [Payname Format](realm-names/payname-format.md) 17 | * [Mint Sub-Realms](realm-names/mint-sub-realms.md) 18 | * [Rules (Subrealms & DMINT)](rules-subrealms-and-dmint.md) 19 | * [Bitwork Mining](bitwork-mining.md) 20 | * [Recursion and References](recursion-and-references.md) 21 | * [Permanent File Storage](permanent-file-storage.md) 22 | * [First is First Candidate System](first-is-first-candidate-system.md) 23 | * [FAQ](faq.md) 24 | 25 | ## Reference & Tools 26 | 27 | * [Specification](reference-and-tools/specification.md) 28 | * [ElectrumX API](reference-and-tools/electrumx-api.md) 29 | * [Javascript Library (CLI)](reference-and-tools/javascript-library-cli.md) 30 | -------------------------------------------------------------------------------- /arc20-tokens/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Fungible Token colored coin standard backed by Satoshis 3 | --- 4 | 5 | # ARC20 Tokens 6 | 7 | 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. 8 | 9 | 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)](https://www.sparrowwallet.com/). 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. 10 | 11 | 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. 12 | 13 | ## Decentralized Mint 14 | 15 | 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. 16 | 17 | ### Initialize (init-dft) 18 | 19 | The basic format of the decentralized initialization using the 20 | [Atomicals CLI](../reference-and-tools/javascript-library-cli.md) is given as: 21 | 22 | ``` 23 | yarn cli init-dft 24 | metadata.json 25 | 26 | Optional flags: 27 | --mintbitworkc= 28 | --satsbyte= 29 | ``` 30 | 31 | _**See format of metadata.json below**_ 32 | 33 | 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`. 34 | 35 | _Note:_ It will take 3 block confirmations before the `tick` ticker will be claimed. You can query the status with `yarn cli get ` or `yarn cli find-tickers` 36 | 37 | **Required Parameters:** 38 | 39 | _tick:_ The globally unique ticker name 40 | 41 | _per\_mint\_amt: Number of units of the token to award per successful mint. Satoshi amount._ 42 | 43 | _mint\_count:_ Total number of permitted mints before exhausting the quota and becoming "fully minted" 44 | 45 | _start\_height:_ Starting block height that mints may be begin. Can set block height to 0 or any future block height. 46 | 47 | _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" 48 | 49 | **Optional Flags:** 50 | 51 | _--mintbitworkc=\_ 52 | 53 | Define an optional [Bitwork](../bitwork-mining.md) 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. 54 | 55 | 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. 56 | 57 | Example time estimates for time required for minters: 58 | 59 | _Note:_ it could be any digit in the range `a-f0-9`, we use all `7's` for illustration purpose only. 60 | 61 | * 3 hex digit prefix of "777" will take about 4 seconds to mine 62 | * 4 hex digit prefix of "7777" will take \~1 minute to mine 63 | * 5 hex digit prefix of "77777" will take \~16 minutes to mine 64 | * 6 hex digit prefix of "777777" will take \~256 minutes to mine 65 | 66 | _--satsbyte=\_ 67 | 68 | Set the satoshis per byte for the transaction and override the default. 69 | 70 | #### Initialize a Perpetual Minting token 71 | 72 | ``` 73 | yarn cli init-dft-perpetual 74 | ``` 75 | 76 | **Important Optional Parameters:** 77 | - `max_mints`: The number of mints allowed per mint phase. (Defaults to `2000`) 78 | - `maxglobalmints`: The number of global max mints. 79 | - `mint_amount`: The number of tokens per mint. (Defaults to `10000`) 80 | - `mint_height`: The starting mint height. 81 | - `mintbitworkvec`: The base vector of the bitwork prefix. 82 | - `mintbitworkcinc`: The amount of `bitworkc` to increase for each phase of `max_mints`. (Defaults to `1`) 83 | - `mintbitworkrinc`: The amount of `bitworkr` to increase for each phase of `max_mints`. 84 | - `mintbitworkcincstart`: The starting amount of `bitworkc` to increase for each phase of `max_mints`. 85 | - `mintbitworkrincstart`: The starting amount of `bitworkr` to increase for each phase of `max_mints`. 86 | 87 | > See the complete arguments list using the command `yarn cli init-dft-perpetual -h`. 88 | 89 | Below is an example of how to initialize a token with the same configuration of $infinity. 90 | 91 | ```shell 92 | yarn cli init-dft-perpetual infinity2 \ 93 | --max_mints=3333 \ 94 | --mint_amount=9999 \ 95 | --mintbitworkvec="888888888888888888888888" \ 96 | --mintbitworkcinc=1 97 | ``` 98 | 99 | In mathematical terms, the relationship between the arguments in the function can be expressed as follows: 100 | 101 | 1. **Target Calculation**: 102 | - \( T_{\text{steps}} = \lfloor \frac{\text{actual\_mints}}{\text{max\_mints}} \rfloor \) 103 | - \( T_{\text{current}} = \text{starting\_target} + (T_{\text{steps}} \cdot \text{target\_increment}) \) 104 | 105 | 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. 106 | 107 | 2. **Bitwork Prefix Derivation**: 108 | - \( \text{multiples} = \frac{T_{\text{current}}}{16} \) 109 | - \( F_{\text{amount}} = \lfloor \text{multiples} \rfloor \) 110 | - \( \text{modulo} = T_{\text{current}} \mod 16 \) 111 | 112 | The resulting bitwork prefix string is derived from the base vector \( \text{bitwork\_vec} \), padded to 32 characters, with: 113 | - The first \( F_{\text{amount}} \) characters forming the primary prefix. 114 | - If \( \text{modulo} > 0 \), it appends \(".\text{modulo}"\) to the prefix. 115 | 116 | ### Mint (mint-dft) 117 | 118 | The basic format of the decentralized mint using the [Atomicals CLI ](../reference-and-tools/javascript-library-cli.md)is given as: 119 | 120 | ``` 121 | yarn cli mint-dft 122 | 123 | Optional flags: 124 | --satsbyte= 125 | ``` 126 | 127 | The decentralized mint function `mint-dft` allows minting for ticker `tick` to proceed starting from block height `start_height`. 128 | 129 | Follow the on-screen instructions to mint. 130 | 131 | **Required Parameters:** 132 | 133 | _tick:_ The globally unique ticker name 134 | 135 | **Optional Flags:** 136 | 137 | _--satsbyte=\_ 138 | 139 | Set the satoshis per byte for the transaction and override the default. 140 | 141 | ## Direct Mint 142 | 143 | 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. 144 | 145 | ### Mint entire supply in one step 146 | 147 | ``` 148 | yarn cli mint-ft metadata.json 149 | 150 | Optional flags: 151 | --satsbyte= 152 | ``` 153 | 154 | _**See format of metadata.json below**_ 155 | 156 | 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. 157 | 158 | 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. 159 | 160 | 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. 161 | 162 | _Note:_ It will take 3 block confirmations before the `tick` ticker will be claimed. You can query the status with `yarn cli get ` or `yarn cli find-tickers` 163 | 164 | **Required Parameters:** 165 | 166 | _tick:_ The globally unique ticker name 167 | 168 | _total\_supply:_ Total supply units to directly mint 169 | 170 | _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" 171 | 172 | **Optional Flags:** 173 | 174 | _--satsbyte=\_ 175 | 176 | Set the satoshis per byte for the transaction and override the default. 177 | 178 | ## Metadata.json Format 179 | 180 | **Define metadata details into the token.** The suggested format to use follows the convention `sample-ft-meta.json.` 181 | 182 | Use [Permanent File Storage](../permanent-file-storage.md) to store an image on-chain and reference it in the "image" field below. 183 | 184 | ```` 185 | ```json 186 | { 187 | "name": "", 188 | "desc": "", 189 | "image": "atom:btc:dat:/image.png", 190 | "decimals": 0, 191 | "links": { 192 | "x": { 193 | "v": "https://x.com/..." 194 | }, 195 | "website": { 196 | "v": "https://..." 197 | }, 198 | "realm": { 199 | "v": "atom:btc:realm:myrealmname.subrealm" 200 | }, 201 | "discord": { 202 | "v": "https://discord.gg/..." 203 | } 204 | }, 205 | "legal": { 206 | "terms": "" 207 | } 208 | } 209 | ``` 210 | ```` 211 | 212 | 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. 213 | 214 |
215 | 216 | ⚡ Get started and mint your first Atomical Digital Object 217 | 218 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 219 | 220 |
221 | -------------------------------------------------------------------------------- /arc20-tokens/normal-transfer-rules.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about Atomicals Fungible Tokens (ARC20) Transfer Rules 3 | --- 4 | 5 | # Normal Transfer Rules 6 | 7 | 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. 8 | 9 | ## Transfers of Fungible Tokens (ARC20) 10 | 11 | Fully allocating - cleanly assign all inputs to outputs with FIFO rule. 12 | 13 | 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.\ 14 | Multiple Atomicals at the same UTXO input are sorted by atomical\_id. Since “1932” is before “7920” it goes first. 15 | 16 |

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

17 | 18 | ## Transfers of Fungible Tokens (ARC20) 19 | 20 | Not cleanly allocating - Performs "best effort" assignment for all tokens from Output 0 21 | 22 | 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.\ 23 | 24 | 25 |
26 | 27 | Atomicals 1932 ,7920, 0542 are Non-Fungible Tokens (NFT) are assigned in First-In First Out order while skipping unspendable outputs (OP\_RETURN).\ 28 | \ 29 | 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. 30 | 31 | ## Transfers of Fungible Tokens (ARC20) 32 | 33 | Insufficient outputs - permanently destroying unallocated units 34 | 35 | Atomical 86a1 is Fungible Tokens (ARC20) and can be split and merged across outputs.\ 36 | \ 37 | 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.\ 38 | 39 | 40 |
41 | 42 | ## Transfers of Fungible Tokens (ARC20) 43 | 44 | Incorrect over-allocation - permanently destroying remainder 45 | 46 | Atomical 86a1 is Fungible Tokens (ARC20) and can be split and merged across outputs.\ 47 | \ 48 | 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 49 | 50 |
51 | -------------------------------------------------------------------------------- /arc20-tokens/substantiation-factor.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: This is only a PRELIMINARY CONCEPT and no implementation exists to date. 3 | --- 4 | 5 | # Substantiation Factor 6 | 7 | > ❗ This is only a **PRELIMINARY CONCEPT** and no implementation exists to date. 8 | 9 | **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. 10 | 11 | ⚡ **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. 12 | 13 | ## Operation: "ST" - Substantiate Token 14 | 15 | 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. 16 | 17 | 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` 18 | 19 | We can then see we can "rescale" or "re-substantiation" by different factors, by changing the exponent to give decimal places. 20 | 21 | Consider the table of Exponents to represent token units with 1:1 backing, then 1:10, then 1:100 satoshis, etc and so on. 22 | 23 | ``` 24 | 10^0 = 1 25 | 10^1 = 10 26 | 10^2 = 100 27 | 10^3 = 1,000 28 | 10^4 = 10,000 29 | 10^5 = 100,000 30 | ``` 31 | 32 | 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. 33 | 34 | An example will demonstrate how this works, preserving the fungibility and fluidity of the ARC20 transfers. 35 | 36 | 37 | 38 |
39 | 40 | In the event there are multiple inputs with different exponents, we can easily handle them too: 41 | 42 | 43 | 44 |
45 | 46 | An example to "downscale" to a lower exponent 47 | 48 | 49 | 50 |
51 | 52 | And one more example to demonstrate the downscaling to make the point extra clear 53 | 54 | 55 | 56 |
57 | 58 | ## Transfers without Operation "ST" 59 | 60 | When the Operation "ST" is not used, then the highest Exponent is taken as the target Exponent, that's all there is to it. 61 | 62 |
63 | -------------------------------------------------------------------------------- /arc20-tokens/swap-transfer-rules.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about Atomicals Fungible Tokens (ARC20) PBST Swap Rules 3 | --- 4 | 5 | # Swap Transfer Rules 6 | 7 | **STEP 1.**\ 8 | 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. 9 | 10 | **STEP 2.**\ 11 | 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. 12 | 13 | 14 | 15 |
16 | -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (1) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (1) (1).png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (1).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (1).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (1).png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (10).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (10).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (14) (1).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (14) (1).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (14).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (14).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (15).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (15).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (16).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (16).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (2) (1).png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (2).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (2).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (2).png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (3).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (3).png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (4).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (4).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (5).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (5).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (6).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (6).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (7).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (7).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (8).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (8).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) (9).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) (9).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) Insuff.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) Insuff.png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) base 1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) base 1.png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) over.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) over.png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20) swap1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20) swap1.png -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20).jpg -------------------------------------------------------------------------------- /assets/Transfers of Fungible Tokens (ARC20).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/Transfers of Fungible Tokens (ARC20).png -------------------------------------------------------------------------------- /assets/WhatsApp Image 2023-12-12 at 9.35.07 AM (1).jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/WhatsApp Image 2023-12-12 at 9.35.07 AM (1).jpeg -------------------------------------------------------------------------------- /assets/WhatsApp Image 2023-12-12 at 9.35.07 AM (2).jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/WhatsApp Image 2023-12-12 at 9.35.07 AM (2).jpeg -------------------------------------------------------------------------------- /assets/WhatsApp Image 2023-12-12 at 9.35.07 AM.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/WhatsApp Image 2023-12-12 at 9.35.07 AM.jpeg -------------------------------------------------------------------------------- /assets/WhatsApp Image 2023-12-12 at 9.35.08 AM (1).jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/WhatsApp Image 2023-12-12 at 9.35.08 AM (1).jpeg -------------------------------------------------------------------------------- /assets/WhatsApp Image 2023-12-12 at 9.35.08 AM.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/WhatsApp Image 2023-12-12 at 9.35.08 AM.jpeg -------------------------------------------------------------------------------- /assets/arqr (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/arqr (1).png -------------------------------------------------------------------------------- /assets/arqr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/arqr.png -------------------------------------------------------------------------------- /assets/atomblack.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/atomblack.jpg -------------------------------------------------------------------------------- /assets/atomicals black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/atomicals black.png -------------------------------------------------------------------------------- /assets/atomicals drawings (2).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/atomicals drawings (2).jpg -------------------------------------------------------------------------------- /assets/atomicals drawings.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/atomicals drawings.jpg -------------------------------------------------------------------------------- /assets/atomicalsbanner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/atomicalsbanner.png -------------------------------------------------------------------------------- /assets/banner (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/banner (1).png -------------------------------------------------------------------------------- /assets/banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/banner.png -------------------------------------------------------------------------------- /assets/banner2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/banner2.png -------------------------------------------------------------------------------- /assets/bannercover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/bannercover.png -------------------------------------------------------------------------------- /assets/bc1pa5hvv3w3wjwfktd63zcng6yeccxg9aa90e34n9jrjw3thgc52reqxw6has.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/bc1pa5hvv3w3wjwfktd63zcng6yeccxg9aa90e34n9jrjw3thgc52reqxw6has.png -------------------------------------------------------------------------------- /assets/burn.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/burn.jpeg -------------------------------------------------------------------------------- /assets/delete.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/delete.jpeg -------------------------------------------------------------------------------- /assets/extract.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/extract.jpeg -------------------------------------------------------------------------------- /assets/merge mixed.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/merge mixed.jpg -------------------------------------------------------------------------------- /assets/newer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/newer.png -------------------------------------------------------------------------------- /assets/qrcode1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/qrcode1.png -------------------------------------------------------------------------------- /assets/qrcode2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/qrcode2.png -------------------------------------------------------------------------------- /assets/qrcode3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/qrcode3.png -------------------------------------------------------------------------------- /assets/rescale.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/rescale.jpg -------------------------------------------------------------------------------- /assets/rescaledust.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/rescaledust.jpg -------------------------------------------------------------------------------- /assets/split mixed.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/split mixed.jpg -------------------------------------------------------------------------------- /assets/split st start.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/split st start.jpg -------------------------------------------------------------------------------- /assets/transfer.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/transfer.jpeg -------------------------------------------------------------------------------- /assets/transferrules.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/transferrules.jpeg -------------------------------------------------------------------------------- /assets/update.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/atomicals-community/atomicals-guide/c7101462833c807a1c11c47eb1c8a44de4994308/assets/update.jpeg -------------------------------------------------------------------------------- /bitwork-mining.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Proof of Work CPU/GPU Mineable Tokens 3 | --- 4 | 5 | # Bitwork Mining 6 | 7 | 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. 8 | 9 | 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. 10 | 11 | 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!)_ 12 | 13 | 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. 14 | 15 | 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... 16 | 17 | Atomicals introduces a novel way to mine proof of work vanity prefixes into token transaction ids. 18 | 19 | ## Fine Tuning Proof of Work Bitwork Prefix 20 | 21 | 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. 22 | 23 | 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. 24 | 25 | 26 | 27 | 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** 28 | 29 | 0\ 30 | 1\ 31 | 2\ 32 | 3\ 33 | 4\ 34 | 5\ 35 | 6\ 36 | 7\ 37 | 8\ 38 | 9\ 39 | a\ 40 | b\ 41 | c\ 42 | d\ 43 | e\ 44 | f 45 | 46 | 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. 47 | 48 |
49 | 50 | ⚡ Get started and mint your first Atomical Digital Object 51 | 52 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 53 | 54 |
55 | 56 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "Atomicals Protocol Guide" 3 | description = "An Introduction to Atomicals Theory and Digital Objects on Bitcoin." 4 | authors = ["Atomicals Community"] 5 | language = "en" 6 | multilingual = false 7 | src = "." 8 | 9 | [preprocessor.katex] 10 | after = ["links"] 11 | -------------------------------------------------------------------------------- /collection-containers/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Overview of Collection Containers for Tokens and Data 3 | --- 4 | 5 | # Collection Containers 6 | 7 | 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. 8 | 9 | > **-> Quick Overview: What is a **_**Container**_**?** 10 | > 11 | > 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 12 | 13 | **📌 To Mint Container Items with DMINT (Decentralized Mint) consult the** [**DMINT Guide**](dmint-guide.md) 14 | 15 | ## Collection Format (Recommended) 16 | 17 | 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.\ 18 | See the [sample collection format](https://github.com/atomicals/atomicals-js/tree/master/templates/containers/sample-collection.json) in github. 19 | 20 | ### name (string - optional) 21 | 22 | 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. 23 | 24 | ### desc (string - optional) 25 | 26 | The _desc_ field defines the detailed description of the collection. 27 | 28 | ### legal (object - recommended) 29 | 30 | The _legal_ section defines legal terms and licensing to make it clear how users and holders of the NFTs may use the data. 31 | 32 | **terms (recommended):** Any specific terms of the collection usage or items usage. 33 | 34 | **license (recommended):** Any type of license code. 35 | 36 | ``` 37 | "legal": { 38 | "terms": "...", 39 | "license": "CC", 40 | } 41 | ``` 42 | 43 | ### links (optional) 44 | 45 | The _links_ section defines additional external resources of interest such as website and social media links. 46 | 47 | ``` 48 | { 49 | "links": { 50 | "x": { 51 | "v": "https://x.com/username" 52 | }, 53 | "website": { 54 | "v": "https://coolwebsite.com" 55 | }, 56 | "discord": { 57 | "v": "https://discord.gg/..." 58 | } 59 | } 60 | } 61 | ``` 62 | 63 | ### attrs (object - optional) 64 | 65 | The _attrs_ section defines the types of attributes, their details such as name, description and possible ranges of values. 66 | 67 | ### items (object - required) 68 | 69 | 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. 70 | 71 | **id (required):** stands for "id" of an item and corresponds to the atomical ID of an NFT 72 | 73 | **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_ 74 | 75 | **n (optional):** stands for "name" of an item 76 | 77 | 
```json
 78 | {
 79 |   "name": "Collection Name",
 80 |   "desc": "Collection description",
 81 |   "image": "atom:btc:dat:<location of store-file data>/image.png",
 82 |   "legal": {
 83 |     "terms": "...",
 84 |     "license": "CC"
 85 |   },
 86 |   "links": {
 87 |         "x": {
 88 |             "v": "https://x.com/..."
 89 |         },
 90 |         "website": {
 91 |             "v": "https://..."
 92 |         },
 93 |         "discord": {
 94 |             "v": "https://discord.gg/..."
 95 |         }
 96 |   },
 97 |   "attrs": [
 98 |     {
 99 |       "name": "bodyarmor",
100 |       "desc": "Type of body armor",
101 |       "type": "string",
102 |       "values": [
103 |         "metal",
104 |         "leather",
105 |         "field"
106 |       ]
107 |     },
108 |     {
109 |       "name": "headcovering",
110 |       "desc": "The type of head covering",
111 |       "type": "string",
112 |       "values": [
113 |         "bandana",
114 |         "helmet",
115 |         "scarf",
116 |         "baseball cap"
117 |       ]
118 |     },
119 |     {
120 |       "name": "stamina",
121 |       "desc": "The stamina of the hero",
122 |       "type": "integer",
123 |       "min": 0,
124 |       "max": 10
125 |     }
126 |   ],
127 |   "items": {
128 |     "0": {
129 |       "id": "84718b469c40b1bcc7cb324b8e24e4e442f88cd913687ea2bc7b3e79d4fc4fdei0",
130 |       "n": "Some Name",
131 |       "a": [
132 |         0,
133 |         3,
134 |         8
135 |       ]
136 |     },
137 |     "1": {
138 |       "id": "1070d7c98304bf5ac9a5addceb13e0ce4e840641f82d71d84cebbdac427c1f4fi0",
139 |       "n": "Another Name",
140 |       "a": [
141 |         1,
142 |         2,
143 |         10
144 |       ]
145 |     },
146 |     "Signature Series 1": {
147 |       "id": "14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0",
148 |       "n": "Special",
149 |       "a": [
150 |         2,
151 |         3,
152 |         7
153 |       ]
154 |     }
155 |   }
156 | }
157 | ```
158 |
159 | 160 | Execute the following commands after formatting your collection data in the format above. 161 | 162 | ``` 163 | // first store the desired main image on chain (see section below) 164 | yarn cli store-file ./path/to/image.png image.png --satsbyte=10 165 | 166 | Success sent tx: db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f 167 | { 168 | "success": true, 169 | "data": { 170 | "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997", 171 | "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f", 172 | "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0" 173 | } 174 | } 175 | 176 | // We will use the dataId above to reference the data on chain 177 | // ie: atom:btc:dat:db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0/image.png 178 | 179 | // Store the collection metadata with the following command: 180 | yarn cli set-container-data #mycollection-name collection.json --satsbyte=10 181 | ``` 182 | 183 | ### Bare Minimum Recommended Collection Format 184 | 185 | 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._ 186 | 187 | 
```json
188 | {
189 |   "name": "Collection Name",
190 |   "image": "atom:btc:dat:<location of store-file data>/image.png",
191 |   "items": {
192 |     "0": {
193 |       "id": "84718b469c40b1bcc7cb324b8e24e4e442f88cd913687ea2bc7b3e79d4fc4fdei0"
194 |     },
195 |     "1": {
196 |       "id": "1070d7c98304bf5ac9a5addceb13e0ce4e840641f82d71d84cebbdac427c1f4fi0"
197 |     },
198 |     "9999": {
199 |       "id": "14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0"
200 |     }
201 |   }
202 | }
203 | ```
204 |
205 | 206 | Execute the following commands after formatting your collection data in the format above. 207 | 208 | ``` 209 | // first store the desired main image on chain (see section below) 210 | yarn cli store-file ./path/to/image.png image.png --satsbyte=10 211 | 212 | Success sent tx: db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f 213 | { 214 | "success": true, 215 | "data": { 216 | "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997", 217 | "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f", 218 | "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0" 219 | } 220 | } 221 | 222 | // We will use the dataId above to reference the data on chain 223 | // ie: atom:btc:dat:db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0/image.png 224 | 225 | // Store the collection metadata with the following command: 226 | yarn cli set-container-data #mycollection-name collection.json --satsbyte=10 227 | ``` 228 | 229 | ## Storing Immutable Image File on Chain 230 | 231 | [permanent-file-storage.md](../permanent-file-storage.md "mention") 232 | 233 | Using the command line utility, execute the following command to set the data in the sample file above. 234 | 235 | ``` 236 | // immutably store an image on-chain to reference in the container metadata 237 | yarn cli store-file ./path/to/image.png image.png --satsbyte=10 238 | 239 | Success sent tx: db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f 240 | { 241 | "success": true, 242 | "data": { 243 | "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997", 244 | "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f", 245 | "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0" 246 | } 247 | } 248 | ``` 249 | 250 | We will use the _reveal location_ (db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0) to refer to the image _image.png_ below. 251 | 252 | ## Adding NFTs to a Collection Container 253 | 254 | Provide a file that matches the collections format above and execute the following command to update the sample #mycollection-name. 255 | 256 | ``` 257 | yarn cli set-container-data #mycollection-name sample-collection.json --satsbyte=10 258 | ``` 259 | 260 | ## Querying Metadata and Items of Collection Container 261 | 262 | After the transaction is confirmed in a block, you may query the state of the sample #mycollection-name with: 263 | 264 | ``` 265 | yarn cli state #mycollection-name 266 | ``` 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 |
277 | 278 | ⚡ Get started and mint your first Atomical Digital Object 279 | 280 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 281 | 282 |
283 | 284 | 285 | 286 | -------------------------------------------------------------------------------- /collection-containers/dmint-guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Atomicals NFT Container DMint Tutorial 3 | --- 4 | 5 | # DMINT Guide 6 | 7 | > The following DMINT Guide is courtesy and written by the [wizz.cash](https://wizz.cash) team. [Original link.](https://astrox.notion.site/Atomicals-NFT-Container-DMint-Tutorial-1bd9216f051942458b3a83268a68fb0c) 8 | 9 | 10 | 11 |
12 | 13 | ## Terms 14 | 15 | | Mint | The process of creating content on a blockchain. It typically involves generating and recording new items on the blockchain. | 16 | |-----------|------------------------------------------------------------------------------------------------------------------------------| 17 | | DMINT | "Decentralized Mint", indicating a decentralized minting operation. | 18 | | Container | A collection or a set of items. | 19 | | Bitwork | The difficulty of minting. The rules for bitwork can be found in the [Bitwork Mining](../bitwork-mining.md). | 20 | | Timestamp | A continuous 10 or 13-digit number used to represent time. | 21 | 22 | ## Overview 23 | 24 | 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.' 25 | 26 | The process can be broadly divided into four main blocks: 27 | 28 | 1. Prepare all data for the collection. 29 | 2. Configure the container. 30 | 3. Validate the NFT item. 31 | 4. Mint the NFT item. 32 | 33 | As a project owner, your focus should be on steps 1, 2, and 3. 34 | 35 | > 💰 Before each step, there is a ⛓️ icon indicating that the operation is on-chain, requiring gas consumption. 36 | 37 | #### **Prepare Collection Data** 38 | 39 | 1. Gather data for all NFTs (A1, A2......AN). 40 | 2. Prepare the DMINT data for the collection (B). 41 | 3. Collect other metadata for the collection (C). 42 | 4. Use the command-line tool to locally create a new wallet for isolating all container operations and avoiding confusion. 43 | 44 | #### **Configure Container** 45 | 46 | 1. ⛓️ Mint the container. 47 | 2. ⛓️ Use the collection data (B) to configure DMINT. 48 | 3. ⛓️ Configure other metadata (C). 49 | 4. ⛓️ Seal the container after confirming all information. **(Final step! Final step!)** 50 | 51 | #### **Validate NFT Item** 52 | 53 | 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. 54 | 2. The container is sealed; you can retrieve the mint status of individual items and the list of items already minted. 55 | 56 | #### **Mint NFT Item** 57 | 58 | 1. ⛓️ Download NFT data (A) and locally mint using the official command-line tool. 59 | 60 | > 📌 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. 61 | 62 | 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. 63 | 64 | *** 65 | 66 | ## **Operation Process** 67 | 68 | The following operations are based on version 0.1.46 of the atomicals-js command-line tool ([@aa34095c](https://github.com/atomicals/atomicals-js/commit/aa34095c673de28166105e26ab2e898179e8039a)). 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](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. 69 | 70 | > 💡 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. 71 | 72 | > ❗ 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. 73 | 74 | > 💰 For each command in the steps with \`--satsbyte\`, please fill in the value based on the on-chain gas situation. 75 | 76 | *** 77 | 78 | ### **Prepare Collection Data** 79 | 80 | 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. 81 | 2. Run a command to generate processed data for all NFTs. After completion, a new folder will be generated. 82 | 83 | ``` 84 | $ yarn cli prepare-dmint-items "path/to/collection-folder" "path/to/output-folder" 85 | ``` 86 | 87 | 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. 88 | 89 | ```json 90 | { 91 | "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98", 92 | "data": { 93 | "args": { 94 | "request_dmitem": "test-1", 95 | "main": "image.jpg", 96 | "i": true 97 | }, 98 | "image.jpg": { 99 | "$b": "ffd8ffe000104a4649460001010100600060000ffd9" 100 | } 101 | } 102 | } 103 | ``` 104 | 105 | 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. 106 | 107 | ``` 108 | yarn cli prepare-dmint "path/to/folder" 0 "b1d0" 109 | ``` 110 | 111 | ```json 112 | { 113 | "dmint": { 114 | "v": "1", 115 | "mint_height": 0, 116 | "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1", 117 | "immutable": true, 118 | "items": 10, 119 | "rules": [ 120 | { 121 | "p": ".*", 122 | "bitworkc": "7baf" 123 | } 124 | ] 125 | } 126 | } 127 | ``` 128 | 129 | From here, `mint_height` can be modified to specify which block your DMINT should start. 130 | For example: `840000` means the DMINT of the container can only start after the `840000` height block has been confirmed. 131 | 132 | ```json 133 | { 134 | "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98", 135 | "data": { 136 | "args": { 137 | "request_dmitem": "test-1", 138 | "main": "image.jpg", 139 | "i": true, 140 | "proof": [ 141 | { 142 | "p": true, 143 | "d": "3212c74b3b5083433a8111f80369d8c591711c577e45dacb8ccaf7960d96790f" 144 | } 145 | ] 146 | }, 147 | "image.jpg": { 148 | "$b": "ffd8ffe000104a4649460001010100600060000ffd9" 149 | } 150 | }, 151 | "targetVector": "test-1:any:any:image.jpg:0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c97", 152 | "targethash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98" 153 | } 154 | ``` 155 | 156 | > ❗ 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. 157 | 158 | 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: 159 | 160 | ```json 161 | { 162 | "dmint": { 163 | "v": "1", 164 | "mint_height": 0, 165 | "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1", 166 | "immutable": true, 167 | "items": 10, 168 | "rules": [ 169 | { 170 | "p": "1$", 171 | "bitworkc": "890a" 172 | }, 173 | { 174 | "p": ".*", 175 | "bitworkc": "7baf" 176 | } 177 | ] 178 | } 179 | } 180 | ``` 181 | 182 | [See Rules Guide for more details](../rules-subrealms-and-dmint.md) 183 | 184 | **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 `$`** 185 | 186 | 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). 187 | 188 | > ❗ 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. 189 | 190 | 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. 191 | 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](https://github.com/atomicals/atomicals-js/blob/master/templates/containers/dmint-collection-general-metadata.json), and adjust it according to your content. 192 | 193 | > ❗ You can refer to the [Collection Containers](README.md#collection-format-recommended) 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. 194 | 195 | *** 196 | 197 | ### Configure Container 198 | 199 | 1. ⛓️ Mint the specified container. If you want to specify a different receiving address, replace "yourWalletAddress" with the corresponding wallet address. 200 | 201 | ``` 202 | $ yarn cli mint-container "#container-name" --initialowner "yourWalletAddress" --satsoutput=1000 --bitworkc="b6cf" --satsbyte=1 203 | ``` 204 | 205 | 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]. 206 | 207 | > ❗ 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. 208 | 209 | ``` 210 | $ yarn cli enable-dmint "#container-name" "dmint-json-path.json" --satsbyte=1 211 | ``` 212 | 213 | 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. 214 | 215 | ``` 216 | $ yarn run cli store-file "path/of/your_logo.png" "logo.png" --satsbyte=1 217 | 218 | ...... 219 | filesData { 220 | 'logo.png': 221 | } 222 | Payload CBOR Size (bytes): 235 223 | Payload Encoded: { 224 | 'logo.png': 225 | } 226 | 227 | ... 228 | Success sent tx: f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7af 229 | { 230 | "success": true, 231 | "data": { 232 | "commitTxid": "c931d7a337eef91f5f6f2b3430c78aaac0e7f11752e15576a1a4881b344457c5", 233 | "revealTxid": "f26bbf1833d6af0ca533cfddbbb1f8074375490120164e6d0a680aca4bacf7af", 234 | "dataId": "f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7afi0" 235 | } 236 | } 237 | ✨ Done in 81.41s. 238 | ``` 239 | 240 | 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. 241 | 242 | ``` 243 | { 244 | "name": "container-name", 245 | "desc": "A test container." 246 | "image": "atom:btc:dat:1a29d1ed20c36a95f6b5c20977a5f1035cc0cd5f55327692149a5710d1d75e9bi0/logo.png", 247 | ... 248 | } 249 | ``` 250 | 251 | 4. ⛓️ After modifying metadata C, set it for the container. 252 | 253 | ``` 254 | $ yarn cli set-container-data "#container-name" "path/to/container-dmint-metadata.json" --satsbyte=1 255 | ``` 256 | 257 | 5. Execute the command to seal the container. 258 | 259 | > ❗ 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. 260 | 261 | ``` 262 | $ yarn cli seal "#container-name" --satsbyte=1 263 | ``` 264 | 265 | *** 266 | 267 | ### **Validate NFT Item** 268 | 269 | 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. 270 | 271 | * 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). 272 | 273 | ``` 274 | $ yarn cli validate-container-item "#container-name" "test-item-3" "path/to/item-3.json" 275 | ``` 276 | 277 | * 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: 278 | 279 | ``` 280 | { 281 | "success": true, 282 | "response": { 283 | "result": { 284 | "status": null, 285 | "candidate_atomical_id": null, 286 | "atomical_id": null, 287 | "candidates": [], 288 | "type": "item", 289 | "applicable_rule": { 290 | "p": ".*", 291 | "bitworkc": "a91b" 292 | }, 293 | "proof_valid": true, 294 | "target_vector": "test-item-3:any:any:image.jpg:3b0bcfe26b7521e83e595f5838d04ea25a45931a849ab5f0db134eb9a4a7cec2", 295 | "target_hash": "8d800be8cb6b418d986a99b9d2fd23994fa712f3c76ef9a3c8306298d2af2ba4", 296 | "dmint": { 297 | "v": "1", 298 | "rules": [ 299 | { 300 | "p": ".*", 301 | "bitworkc": "a91b" 302 | } 303 | ], 304 | "merkle": "b68ace0edff5f81a92acc57e493d6d3cfa7cfc038bfe0397dfb81d082bd3b9d0", 305 | "immutable": true, 306 | "mint_height": 0 307 | } 308 | } 309 | } 310 | } 311 | ``` 312 | 313 | > ❗ It is recommended to validate each item to ensure the effectiveness of all data. 314 | 315 | ### **Mint NFT Item** 316 | 317 | 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. 318 | 319 | ``` 320 | $ yarn cli mint-item "#container-name" "item-name" "path/to/item-name.json" --satsbyte=1 321 | ``` 322 | 323 | *** 324 | 325 | ## Advanced Topic: Mint Payment Rules 326 | 327 | 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. 328 | 329 | 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_" 330 | 331 | ```` 332 | ```json 333 | { 334 | "dmint": { 335 | "v": "1", 336 | "items": 1000, 337 | "rules": [ 338 | { 339 | "o": { 340 | "5120a1519da5fead1a2e6cc803aedbd79a756f5e0eaafccae641c16e0612fb03071c": { 341 | "v": 10000 342 | } 343 | }, 344 | "p": "hi$", 345 | "bitworkc": "888" 346 | }, 347 | { 348 | "o": { 349 | "5120a9519da5fead1a2e6cc803acebd79a756f5e0eaafccae641c16e0612fb03072c": { 350 | "v": 2000 351 | } 352 | }, 353 | "p": ".*", 354 | "bitworkc": "7777" 355 | } 356 | ], 357 | "merkle": "12e772dc28611968e3f203827ed9c71e0a1e25071032d565b6fb9afee94dd344", 358 | "immutable": true, 359 | "mint_height": 0 360 | } 361 | } 362 | ``` 363 | ```` 364 | 365 | In the event that an item minted requires payment, the status of the NFT will indicate that payment is expected for the leading candidate. 366 | 367 | 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. 368 | 369 | From the [atomical-js CLI:](https://github.com/atomicals/atomicals-js) 370 | 371 | ``` 372 | yarn cli transfer-builder --atomicalreceipt --owner funding --atomicalreceipttype d --satsbyte=80 373 | ``` 374 | 375 | 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. 376 | 377 | ## **Optional Operations** 378 | 379 | The container is already sealed, and users can now begin minting. In the case where some items have already been minted: 380 | 381 | ### Query the status of a single item 382 | 383 | `get-container-item` 384 | 385 | ``` 386 | $ yarn cli get-container-item "#container-name" "test-item-4" 387 | ``` 388 | 389 | ### **Query Minted Items** 390 | 391 | 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`**). 392 | 393 | ``` 394 | $ yarn cli get-container-items "#container-name" limit offset 395 | ``` 396 | -------------------------------------------------------------------------------- /faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Frequently Asked Questions About The Atomicals Protocol 3 | --- 4 | 5 | # FAQ 6 | 7 | ## What is the Atomicals Protocol? 8 | 9 | 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. 10 | 11 | ## Does Atomicals require a separate chain, additional layers or any changes to Bitcoin? 12 | 13 | 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. 14 | 15 | ## What can Atomicals Digital Objects be used for? 16 | 17 | 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: 18 | 19 | * Digital collectibles, media and art 20 | * Digital identity, authentication and token-gated content 21 | * Web hosting and file storage 22 | * Peer to peer exchange and atomic swaps 23 | * Digital namespace allocation 24 | * Virtual land and title registries 25 | * Dynamic objects and state for games 26 | * Social media profiles, posts and communities 27 | 28 | 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.](reference-and-tools/javascript-library-cli.md) 29 | 30 | ## How does Atomicals Protocol work? 31 | 32 | Learn more about how the protocol works by visiting the Protocol Specification page. 33 | 34 | {% include "reference-and-tools/specification.md" %} 35 | 36 | ## Why are Atomicals called "digital objects" instead of "NFTs"? 37 | 38 | 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. 39 | 40 | -------------------------------------------------------------------------------- /first-is-first-candidate-system.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Theory of Operations of how names, tickers and other assets are claimed First 4 | is First. 5 | --- 6 | 7 | # First is First Candidate System 8 | 9 | Coming soon.... 10 | -------------------------------------------------------------------------------- /nfts/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Atomicals Digital Objects or "atoms" for short. 3 | --- 4 | 5 | # NFTs 6 | 7 | ## What are Atomicals Digital Objects? 8 | 9 | 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.** 10 | 11 | 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. 12 | 13 | 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. 14 | 15 | ## How Atomicals Digital Objects Are Created 16 | 17 | 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. 18 | 19 | [Mint your first Atomical using the command line interface](https://github.com/atomicals/atomicals-js) with nothing more than your existing Bitcoin wallet. 20 | 21 | 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. 22 | 23 | ## How Atomicals Digital Objects Are Updated 24 | 25 | 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. 26 | 27 | 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. 28 | 29 | 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. 30 | 31 | ## How Atomicals Digital Objects Are Transferred 32 | 33 | An Atomical, once minted, is transferred like regular Bitcoins using any address format type include Taproot (P2TR), SegWit, Multisig, and legacy address (P2PKH). 34 | 35 | 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. 36 | 37 | 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. 38 | 39 | Read about [NFT Transfer Rules](normal-transfer-rules.md) and[ NFT Swap Rules](swap-transfer-rules.md). 40 | 41 | ## Dynamic Digital Object State 42 | 43 | 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.\ 44 | 45 | 46 | > ⚡ Get started and mint your first Atomical Digital Object 47 | > 48 | > [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions 49 | 50 | 51 | 52 |
53 | 54 | ⚡ Get started and mint your first Atomical Digital Object 55 | 56 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 57 | 58 |
59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | -------------------------------------------------------------------------------- /nfts/normal-transfer-rules.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about Atomicals Non-Fungible Tokens (NFT) Transfer Rules 3 | --- 4 | 5 | # Normal Transfer Rules 6 | 7 | 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. 8 | 9 | ## Transfers of Non-Fungible Tokens (NFT) 10 | 11 | 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. 12 | 13 |
14 | -------------------------------------------------------------------------------- /nfts/splat-operation.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Separate (or "splat") merged NFTs at the same UTXO location to their own 4 | outputs 5 | --- 6 | 7 | # Splat Operation 8 | 9 | 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. 10 | 11 | Examples: 12 | 13 | Atomicals 1199 ,4567, 0542 are Non-Fungible Tokens (NFT) merged in a single UTXO.\ 14 | \ 15 | To separate them, use the SPLAT (x) operation to spread them out over the outputs in alphabetical order according to their atomical\_id. 16 | 17 | 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. 18 | 19 | 20 | 21 |
22 | 23 | \ 24 | 25 | 26 | \ 27 | -------------------------------------------------------------------------------- /nfts/swap-transfer-rules.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about Atomicals Non-Fungible Tokens (NFT) PBST Swap Rules 3 | --- 4 | 5 | # Swap Transfer Rules 6 | 7 | STEP 1.\ 8 | Seller signs 2nd input containing the NFT Atomical 7771 and 2nd output to receive 4000 Satoshis.\ 9 | Signing with SIGHASH\_SINGLE | ANYONECANPAY allows the buyer to add additional inputs for funding and their receive address for where to receive the NFT 10 | 11 | \ 12 | STEP 2.\ 13 | 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. 14 | 15 |
16 | -------------------------------------------------------------------------------- /permanent-file-storage.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Store files and data immutably for the scenarios when it's not needed to 4 | create a dynamic Atomical Digital Object 5 | --- 6 | 7 | # Permanent File Storage 8 | 9 | ## Example: Storing Immutable Image File on Chain 10 | 11 | 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)_ 12 | 13 | ``` 14 | // immutably store an image on-chain to reference in the container metadata 15 | yarn cli store-file ./path/to/image.png image.png --satsbyte=10 16 | 17 | Success sent tx: db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f 18 | { 19 | "success": true, 20 | "data": { 21 | "commitTxid": "b57bad8c0b7f58a552574fafc16b6efbbb3bf966b9ccfb24f03580f9462b5997", 22 | "revealTxid": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461f", 23 | "dataId": "db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0" 24 | } 25 | } 26 | ``` 27 | 28 | We will use the _reveal location_ (db8a761ed493627138c5733071558c4caa65912c5cba3e1061c02d6d7933461fi0) to refer to the image _image.png_ below. 29 | 30 | Now that the file is on chain, use the [recursion and references URN](recursion-and-references.md) syntax to refer to the file. 31 | -------------------------------------------------------------------------------- /realm-names/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Overview of Realm Digital Objects (Realm Name Service) 3 | --- 4 | 5 | # Realm Names 6 | 7 | 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](https://realm.name) 8 | 9 |

Claim your Realm +name on Bitcoin @ https://realm.name

10 | 11 | > **-> What is a **_**Realm**_**?** 12 | > 13 | > 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. 14 | 15 | ### 16 | 17 |
18 | 19 | ### Mint Realm 20 | 21 | Before using the commands below you must first create a local wallet using the `wallet-init` command. For convenience the commands. 22 | 23 | #### Step 1. Download and Install atomicals-js CLI 24 | 25 | Download and install the [atomicals-js](https://github.com/atomicals/atomicals-js) CLI. 26 | 27 | 
git clone https://github.com/atomicals/atomicals-js.git
 28 | cd atomicals-js
 29 | yarn install
 30 | yarn build
 31 |
32 | 33 | #### Step 2. Wallet Initialize 34 | 35 | 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!_ 36 | 37 | To initialize a new `wallet.json` file that will store your address for receiving change use the `wallet-init` command. 38 | 39 | ``` 40 | yarn cli wallet-init 41 | 42 | >>> 43 | 44 | Wallet created at wallet.json 45 | phrase: maple maple maple maple maple maple maple maple maple maple maple maple 46 | Legacy address (for change): 1FXL2CJ9nAC...u3e9Evdsa2pKrPhkag 47 | Derive Path: m/44'/0'/0'/0/0 48 | WIF: L5Sa65gNR6QsBjqK.....r6o4YzcqNRnJ1p4a6GPxqQQ 49 | ------------------------------------------------------ 50 | ``` 51 | 52 | #### Step 3. Mint Realm 53 | 54 | The basic format to mint a Realm name using the [Atomicals CLI ](../reference-and-tools/javascript-library-cli.md)is: 55 | 56 | 
yarn cli mint-realm "myrealmname"
 57 | 
 58 | Optional flags:
 59 | --satsbyte=<number>
 60 |
61 | 62 | The realm mint function `mint-realm` allows minting for Realm `myrealmname` as long as you are the first to claim it. 63 | 64 | Follow the on-screen instructions to pay and mint. 65 | 66 | **Required Parameters:** 67 | 68 | _realmname:_ The globally unique realm name 69 | 70 | **Optional Flags:** 71 | 72 | _--satsbyte=\_ 73 | 74 | Set the satoshis per byte for the transaction and override the default. 75 | 76 | #### Step 4. Query Realm name 77 | 78 | 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: 79 | 80 | 
yarn cli get +myrealmname
 81 |
82 | 83 | You may also query and search Realm names on [https://realm.name](https://realm.name) 84 | 85 | #### Step 5. Query global feed (optional) 86 | 87 | You can query the global feed of registered Realms and Atomicals: 88 | 89 | 
yarn cli list
 90 |
91 | 92 |
93 | 94 | ⚡ Get started and mint your first Atomical Digital Object 95 | 96 | [Download and install the Atomicals Javascript CLI tool](https://github.com/atomicals/atomicals-js) and follow the quick start instructions to mint your NFT, Collection, or Realm name in less than 2 minutes. 97 | 98 |
99 | 100 | 101 | 102 | 103 | 104 | \ 105 | 106 | 107 | -------------------------------------------------------------------------------- /realm-names/mint-sub-realms.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Every Realm and Sub-Realm has the ability to mint any number of Sub-Realms 4 | below them. 5 | --- 6 | 7 | # Mint Sub-Realms 8 | 9 |
10 | 11 | ## Method 1: Mint with Sub-Realm Rules 12 | 13 | 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. 14 | 15 | ### Pre-Requisites 16 | 17 | * You have a Realm or Sub-Realm already claimed 18 | * Decide how you will allow user's to mint subrealms (more on this below) 19 | 20 | ### Step 1. Create initial Subrealm Minting Rules File 21 | 22 | [See Rules Guide for more details](../rules-subrealms-and-dmint.md) 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` 23 | 24 | The example demo Realm`+mycoolrealm` exists on testnet at atomical\_id`285051d51bb9d045d24dc0816d6f29bfe72b1c91e479702ec866c724a0f4aa56i0` 25 | 26 | **Sample Rules File (Save as rules.json)** 27 | 28 | ```` 29 | ```json 30 | { 31 | "subrealms": { 32 | "rules": [ 33 | { 34 | "p": "^[a-z0-9]{6,64}$", 35 | "bitworkc": "8888.8" 36 | }, 37 | { 38 | "p": ".*", 39 | "o": { 40 | "0014383fb23c5b1b40025b0e1dd3e310d6e1ee6d316e": { 41 | "v": 1000 42 | } 43 | } 44 | } 45 | ] 46 | } 47 | } 48 | ``` 49 | ```` 50 | 51 | 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](../bitwork-mining.md) 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. 52 | 53 | Recall that you can convert between output script hex format to addresses and vice versa using the CLI tool. See [Rules Guide](../rules-subrealms-and-dmint.md) for more details. 54 | 55 | ### Step 2. Set the Minting Rules with "enable-subrealms" for your Realm 56 | 57 | With the rules file you have created above in Step 1, we will enable it for your particular Realm. 58 | 59 | Using the CLI, execute the following command to enable subrealm minting: 60 | 61 | ``` 62 | yarn cli enable-subrealms +mycoolrealm file.json --satsbyte=100 63 | ``` 64 | 65 | 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. 66 | 67 | ### Step 3. Query "realm-info" to see activated rules 68 | 69 | 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: 70 | 71 | ``` 72 | yarn cli realm-info mycoolrealm 73 | ``` 74 | 75 | It will display the relevant information about the Realm and the activated rules. 76 | 77 | > **⭐ Congratulations! You have successfully enabled Subrealm Minting on your Realm or Subrealms.** Read below on how your users can participate and claim subrealms 78 | 79 | ### Mint and Claim Subrealm 80 | 81 | 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. 82 | 83 | #### Step 1. Query the Subrealm to claim to check if is available 84 | 85 | 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. 86 | 87 | ``` 88 | yarn cli realm-info mycoolrealm.nicesubrealm 89 | ``` 90 | 91 | #### Step 2. Mint the Subrealm Request 92 | 93 | ``` 94 | yarn cli mint-subrealm +mycoolrealm.nicesubrealm --satsbyte=100 95 | ``` 96 | 97 | 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. 98 | 99 | #### Step 3. (If payment is required) Make payment for Subrealm during payment window. 100 | 101 | The CLI has the operation to see which Subrealms are ready to be paid and also help pay with regular Satoshis: 102 | 103 | ``` 104 | yarn cli pending-subrealms 105 | ``` 106 | 107 | Then follow the on-screen instructions to make regular Satoshi payments. 108 | 109 | **⚠️ 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.** 110 | 111 | 112 | 113 | 114 | 115 | -------------------------------------------------------------------------------- /realm-names/payname-format.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Send and receive crypto with human readable payment names powered by the 4 | Atomicals Realms Protocol. 5 | --- 6 | 7 | # Payname Format 8 | 9 | ### Format Convention 10 | 11 | 
+[inbox]@[realm_name]
12 | 
13 | Where:
14 | + is always required at the front to denote it is a Realm user recipient
15 | 
16 | inbox: The name of the inbox associated with the Realm payment name
17 | 
18 | @ is required to indicate the inbox is located at the Realm
19 | 
20 | realm_name: The fully qualified Realm or Subrealm name
21 |
22 | 23 | **Examples** 24 | 25 | ``` 26 | +hello@samplerealm 27 | +main@samplerealm 28 | +support@samplerealm 29 | ``` 30 | 31 | 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. 32 | 33 | ## On-Chain Data Object Format 34 | 35 | To see how to store the data for a Realm, consider the following format layout for a Realm/NFT. 36 | 37 | ``` 38 | { 39 | "paynames": { 40 | "delegate": "atom:btc:id:/paynames", 41 | "hello": { 42 | "delegate": "atom:btc:id:/paynames/hello" 43 | }, 44 | "main": { 45 | "types": { 46 | "btc": { 47 | "value": "bitcoin btc address" 48 | }, 49 | "ltc": { 50 | "value": "litecoin ltc address", 51 | "notes": "optional notes", 52 | "instructions": "optional instructions" 53 | } 54 | } 55 | } 56 | } 57 | } 58 | ``` 59 | 60 | ### Fields 61 | 62 | **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. 63 | 64 | **types:** The tickers for the various cryptocurrencies and payment types accepted 65 | 66 | **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) 67 | 68 | 69 | 70 | -------------------------------------------------------------------------------- /recursion-and-references.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Create hierarchies and includes of Atomicals digital objects with recursion 4 | and references 5 | --- 6 | 7 | # Recursion and References 8 | 9 | The following URNs are defined to simplify including and referencing different Atomicals resources. 10 | 11 | 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. 12 | 13 | Examples of Recursion with References in the `ctx` field: 14 | 15 | ``` 16 | { 17 | // Any Atomical data above... 18 | "ctx": { 19 | // Implied to always get the latest data for an atomical: 20 | "resourcename": "atom:btc:id:/mydata", 21 | // Gets permanent data file image.png at the dat_id 22 | "icon": "atom:btc:dat:/image.png", 23 | // Gets the minted "name" property for a collection 24 | "collection-name": "atom:btc:container:$name", 25 | // Gets the latest version of import.js located at a realm name 26 | "assetbuilder.js": "atom:btc:realm:/import.js", 27 | }, 28 | // Another other Atomical data ... 29 | } 30 | ``` 31 | 32 | **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. 33 | 34 | ## Conventions 35 | 36 | 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. 37 | 38 | The basic form of the Atomicals Universal Resource Name (URN) is: 39 | 40 | **atom:\:\:\\[$ or /\[\]]** 41 | 42 | Where: 43 | 44 | **chain:** The referenced blockchain, set to "BTC" for Bitcoin 45 | 46 | **ref\_type:** The type of reference. Currently supported "**id", "container", "realm", and "dat"** 47 | 48 | **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"_ 49 | 50 | **$ or /:** Whether to refer to the mint (original) data (using dollar sign $) or the dynamic (latest) data (using slash /) of a file for an Atomical. You will notice that for the `dat` ref\_type either $ or / is acceptable and will return the same data regardless. 51 | 52 | **file:** The name of the file is optional, if omitted then general information about the resource is returned 53 | 54 | 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. 55 | 56 | ## References by Atomical ID 57 | 58 | **Get general information** 59 | 60 | atom:btc:id:\ 61 | 62 | Ex: atom:btc:id:14a0d7c98304bf5ac9a5addceb1de0ce4e840641f82d71d84cebbdac427c1fc3i0 63 | 64 | **Get original minted data as JSON** 65 | 66 | atom:btc:id:\$ 67 | 68 | **Get original minted file** 69 | 70 | atom:btc:id:\$links 71 | 72 | atom:btc:id:\$info.pdf 73 | 74 | **Get latest dynamic data state** 75 | 76 | atom:btc:id:\/ 77 | 78 | **Get latest version of a file** 79 | 80 | atom:btc:id:\/image.png 81 | 82 | **Get specific version of a file** 83 | 84 | atom:btc:id:\/image.png@\[txid or version number or blockheight] 85 | 86 | The \[txid or version number or blockheight] can be of the form: 87 | 88 | * hexadecimal of the txid that was one of the valid updates to the file 89 | * Version number starting with "v" such as "v1" 90 | * Block height for the state of the file as of that block height 91 | 92 | ## References by Container Name 93 | 94 | **Get general information** 95 | 96 | atom:btc:container:\ 97 | 98 | Examples: \ 99 | atom:btc:id:my-coolcontainer-name 100 | 101 | **Get original minted data** 102 | 103 | atom:btc:container:\$ 104 | 105 | **Get latest dynamic data state** 106 | 107 | atom:btc:container:\/ 108 | 109 | **Get original minted file** 110 | 111 | atom:btc:container:\$image.jpg 112 | 113 | **Get latest version of a file** 114 | 115 | atom:btc:container:\/items 116 | 117 | **Get specific version of a file** 118 | 119 | atom:btc:container:\/items@\[txid or version number] 120 | 121 | ## References by Realms 122 | 123 | **Get general information** 124 | 125 | atom:btc:realm:\ 126 | 127 | Where realmName can be a Top Realm or any Sub Realm 128 | 129 | Examples: \ 130 | atom:btc:realm:myrealm\ 131 | atom:btc:realm:myrealm.somesubrealm\ 132 | atom:btc:realm:myrealm.somesubrealm.thirdlevel-subrealm 133 | 134 | **Get latest version of a file** 135 | 136 | atom:btc:realm:\/profile 137 | 138 | **Get specific version of a file** 139 | 140 | atom:btc:realm:\/profile@\[txid or version number] 141 | 142 | The \[txid or version number or blockheight] can be of the form: 143 | 144 | * hexadecimal of the txid that was one of the valid updates to the file 145 | * Version number starting with "v" such as "v1" 146 | * Block height for the state of the file as of that block height 147 | 148 | ## References by ARC20 (Fungible Tokens) 149 | 150 | **Get general information** 151 | 152 | atom:btc:arc:\ 153 | 154 | Where ticker can be a ticker name of an ARC20 token 155 | 156 | **Get mint original data** 157 | 158 | atom:btc:arc:\$ 159 | 160 | atom:btc:arc:\/icon.png 161 | 162 | **Get event feed at ticker** 163 | 164 | atom:btc:arc:\/events (To be determined - TBD) 165 | 166 | ## References to Immutable Data 167 | 168 | To store immutable (non digital object data) use the "dat" command (store-file) and reference it using the _dat_ URN of the form: 169 | 170 | atom:btc:dat:\/image.png 171 | 172 | 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. 173 | 174 | 175 | 176 | -------------------------------------------------------------------------------- /reference-and-tools/electrumx-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about the Decentralized Atomicals ElectrumX Index Service 3 | --- 4 | 5 | # ElectrumX API 6 | 7 | [Open The Atomicals ElectrumX API Documentation](https://github.com/atomicals/atomicals-electrumx) 8 | -------------------------------------------------------------------------------- /reference-and-tools/javascript-library-cli.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Interact with Atomicals using the Command Line Interface (CLI) Javascript 4 | Library 5 | --- 6 | 7 | # Javascript Library (CLI) 8 | 9 | Get the Command Line Interface (CLI) from Github: 10 | 11 | [Atomicals GitHub Repository](https://github.com/atomicals/atomicals-js) 12 | 13 | #### 14 | -------------------------------------------------------------------------------- /reference-and-tools/specification.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Detailed Documentation of Atomicals Protocol 3 | --- 4 | 5 | # Specification 6 | 7 | The heart of Atomicals Protocol is a **few simple rules** to follow for mint, transfer, update, delete and extract operations. 8 | After getting acquainted with the theory, jump to [minting your first Atomical Digital Object](javascript-library-cli.md) in a few minutes 9 | 10 | ## ⚠️Warning: The specification is defined in code. Review the commands in the [atomicals-js CLI](https://github.com/atomicals/atomicals-js/tree/master/lib/commands) to see how they function accurately. 11 | 12 | ## Envelope 13 | 14 | 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. 15 | 16 | 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. 17 | 18 | ``` 19 | OP_FALSE 20 | OP_IF 21 | 0x0461746F6D // Push "atom" 4 bytes 22 | // Followed by a single push to denote the operation type 23 | // Payload (CBOR encoded) for the operation 24 | OP_ENDIF 25 | ``` 26 | 27 | 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: 28 | 29 | ``` 30 | 31 | OP_CHECKSIG // Perform a check signature against the pubkey-hash 32 | OP_FALSE 33 | OP_IF 34 | 0x0461746F6D // Push "atom" 4 bytes 35 | // Followed by a single push to denote the operation type 36 | // Payload (CBOR encoded) for the operation 37 | OP_ENDIF 38 | ``` 39 | 40 | The format of the `` field is a single push data representing the type of operation that follows. The `` data is interpreted in the context of the operation type. The `` is a [CBOR](https://cbor.io/) 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. 41 | 42 | 43 | 44 | ## **Payload Format Description** 45 | 46 | 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"` 47 | 48 | The payload is [CBOR encoded](https://cbor.io/) 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. 49 | 50 | 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. 51 | 52 | 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. 53 | 54 | ### Sample Payload Format 55 | 56 | ``` 57 | { 58 | "someimage.png": "binary data", 59 | "meta": { 60 | "some": "value", 61 | "another: { 62 | "fieldabc": 123 63 | } 64 | }, 65 | "args": { 66 | "r": "abc" 67 | } 68 | } 69 | ``` 70 | -------------------------------------------------------------------------------- /rules-subrealms-and-dmint.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Overview of the Rules system for claiming Subrealms and DMINT 3 | --- 4 | 5 | # Rules (Subrealms & DMINT) 6 | 7 | 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. 8 | 9 | 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](arc20-tokens/) token. 10 | 11 | ## Format of Rules Data-structure 12 | 13 | The `rules` section in the `dmint` (for containers) and `subrealms` section for Realms is identical and has the same syntax and semantics. 14 | 15 | We demonstrate the use of the rules, by building upon simple examples and gradually increasing complexity. 16 | 17 | 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 `$` 18 | 19 | ### Example 1: Require only Bitworkc mining to claim mint 20 | 21 | 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. 22 | 23 | ```` 24 | ```json 25 | { 26 | "rules": [ 27 | { 28 | "p": ".*", 29 | "bitworkc": "1234" 30 | } 31 | ] 32 | } 33 | ``` 34 | ```` 35 | 36 | ### Example 2: Require both Bitworkc and Bitworkr mining to claim mint 37 | 38 | 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). 39 | 40 | ```` 41 | ```json 42 | { 43 | "rules": [ 44 | { 45 | "p": ".*", 46 | "bitworkc": "1234", 47 | "bitworkr": "8888.10" 48 | } 49 | ] 50 | } 51 | ``` 52 | ```` 53 | 54 | ### Example 3: Require different Bitworkc based on the name of the item 55 | 56 | 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) 57 | 58 | ```` 59 | ```json 60 | { 61 | "rules": [ 62 | { 63 | "p": "^0|\.gif$", 64 | "bitworkc": "77777" 65 | }, 66 | { 67 | "p": ".*", 68 | "bitworkc": "7777" 69 | } 70 | ] 71 | } 72 | ``` 73 | ```` 74 | 75 | ### Example 4: Require a payment to a certain address to claim the item 76 | 77 | To enable "pay to claim" use the `"o"` (output script) field to indicate what output must be paid in order to successfully claim. 78 | 79 | ```` 80 | ```json 81 | { 82 | "rules": [ 83 | { 84 | "p": ".*", 85 | "o": { 86 | "5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4": { 87 | "v": 1000 88 | } 89 | }, 90 | } 91 | ] 92 | } 93 | ``` 94 | ```` 95 | 96 | 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` 97 | 98 | **Note: Use the CLI utility commands "yarn cli script-address \