Code Monkey home page Code Monkey logo

ord's Introduction

ord

ord is an index, block explorer, and command-line wallet. It is experimental software with no warranty. See LICENSE for more details.

Ordinal theory imbues satoshis with numismatic value, allowing them to be collected and traded as curios.

Ordinal numbers are serial numbers for satoshis, assigned in the order in which they are mined, and preserved across transactions.

See the docs for documentation and guides.

See the BIP for a technical description of the assignment and transfer algorithm.

See the project board for currently prioritized issues.

Join the Discord server to chat with fellow ordinal degenerates.

Donate

Ordinals is open-source and community funded. The current lead maintainer of ord is raphjaph. Raph's work on ord is entirely funded by donations. If you can, please consider donating!

The donation address is bc1qguzk63exy7h5uygg8m2tcenca094a8t464jfyvrmr0s6wkt74wls3zr5m3.

This address is 2 of 4 multisig wallet with keys held by raphjaph, erin, rodarmor, and ordinally.

Bitcoin received will go towards funding maintenance and development of ord, as well as hosting costs for ordinals.com.

Thank you for donating!

Wallet

ord relies on Bitcoin Core for private key management and transaction signing. This has a number of implications that you must understand in order to use ord wallet commands safely:

  • Bitcoin Core is not aware of inscriptions and does not perform sat control. Using bitcoin-cli commands and RPC calls with ord wallets may lead to loss of inscriptions.

  • ord wallet commands automatically load the ord wallet given by the --name option, which defaults to 'ord'. Keep in mind that after running an ord wallet command, an ord wallet may be loaded.

  • Because ord has access to your Bitcoin Core wallets, ord should not be used with wallets that contain a material amount of funds. Keep ordinal and cardinal wallets segregated.

Pre-alpha wallet migration

Alpha ord wallets are not compatible with wallets created by previous versions of ord. To migrate, use ord wallet send from the old wallet to send sats and inscriptions to addresses generated by the new wallet with ord wallet receive.

Installation

ord is written in Rust and can be built from source. Pre-built binaries are available on the releases page.

You can install the latest pre-built binary from the command line with:

curl --proto '=https' --tlsv1.2 -fsLS https://ordinals.com/install.sh | bash -s

Once ord is installed, you should be able to run ord --version on the command line.

Building

On Linux, ord requires libssl-dev when building from source.

On Debian-derived Linux distributions, including Ubuntu:

sudo apt-get install pkg-config libssl-dev build-essential

On Red Hat-derived Linux distributions:

yum install -y pkgconfig openssl-devel
yum groupinstall "Development Tools"

You'll also need Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone the ord repo:

git clone https://github.com/ordinals/ord.git
cd ord

To build a specific version of ord, first checkout that version:

git checkout <VERSION>

And finally to actually build ord:

cargo build --release

Once built, the ord binary can be found at ./target/release/ord.

ord requires rustc version 1.76.0 or later. Run rustc --version to ensure you have this version. Run rustup update to get the latest stable release.

Docker

A Docker image can be built with:

docker build -t ordinals/ord .

Homebrew

ord is available in Homebrew:

brew install ord

Debian Package

To build a .deb package:

cargo install cargo-deb
cargo deb

Contributing

If you wish to contribute there are a couple things that are helpful to know. We put a lot of emphasis on proper testing in the code base, with three broad categories of tests: unit, integration and fuzz. Unit tests can usually be found at the bottom of a file in a mod block called tests. If you add or modify a function please also add a corresponding test. Integration tests try to test end-to-end functionality by executing a subcommand of the binary. Those can be found in the tests directory. We don't have a lot of fuzzing but the basic structure of how we do it can be found in the fuzz directory.

We strongly recommend installing just to make running the tests easier. To run our CI test suite you would do:

just ci

This corresponds to the commands:

cargo fmt -- --check
cargo test --all
cargo test --all -- --ignored

Have a look at the justfile to see some more helpful recipes (commands). Here are a couple more good ones:

just fmt
just fuzz
just doc
just watch ltest --all

If the tests are failing or hanging, you might need to increase the maximum number of open files by running ulimit -n 1024 in your shell before you run the tests, or in your shell configuration.

We also try to follow a TDD (Test-Driven-Development) approach, which means we use tests as a way to get visibility into the code. Tests have to run fast for that reason so that the feedback loop between making a change, running the test and seeing the result is small. To facilitate that we created a mocked Bitcoin Core instance in mockcore

Syncing

ord requires a synced bitcoind node with -txindex to build the index of satoshi locations. ord communicates with bitcoind via RPC.

If bitcoind is run locally by the same user, without additional configuration, ord should find it automatically by reading the .cookie file from bitcoind's datadir, and connecting using the default RPC port.

If bitcoind is not on mainnet, is not run by the same user, has a non-default datadir, or a non-default port, you'll need to pass additional flags to ord. See ord --help for details.

bitcoind RPC Authentication

ord makes RPC calls to bitcoind, which usually requires a username and password.

By default, ord looks a username and password in the cookie file created by bitcoind.

The cookie file path can be configured using --cookie-file:

ord --cookie-file /path/to/cookie/file server

Alternatively, ord can be supplied with a username and password on the command line:

ord --bitcoin-rpc-username foo --bitcoin-rpc-password bar server

Using environment variables:

export ORD_BITCOIN_RPC_USERNAME=foo
export ORD_BITCOIN_RPC_PASSWORD=bar
ord server

Or in the config file:

bitcoin_rpc_username: foo
bitcoin_rpc_password: bar

Logging

ord uses env_logger. Set the RUST_LOG environment variable in order to turn on logging. For example, run the server and show info-level log messages and above:

$ RUST_LOG=info cargo run server

Set the RUST_BACKTRACE environment variable in order to turn on full rust backtrace. For example, run the server and turn on debugging and full backtrace:

$ RUST_BACKTRACE=1 RUST_LOG=debug ord server

New Releases

Release commit messages use the following template:

Release x.y.z

- Bump version: x.y.z โ†’ x.y.z
- Update changelog
- Update changelog contributor credits
- Update dependencies

Translations

To translate the docs we use mdBook i18n helper.

See mdbook-i18n-helpers usage guide for help.

Adding a new translations is somewhat involved, so feel free to start translation and open a pull request, even if your translation is incomplete.

Take a look at this commit for an example of adding a new translation. A maintainer will help you integrate it into our build system.

To start a new translation:

  1. Install mdbook, mdbook-i18n-helpers, and mdbook-linkcheck:

    cargo install mdbook mdbook-i18n-helpers mdbook-linkcheck
    
  2. Generate a new pot file named messages.pot:

    MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}'
    mdbook build -d po
    
  3. Run msgmerge on XX.po where XX is the two-letter ISO-639 code for the language you are translating into. This will update the po file with the text of the most recent English version:

    msgmerge --update po/XX.po po/messages.pot
    
  4. Untranslated sections are marked with #, fuzzy in XX.po. Edit the msgstr string with the translated text.

  5. Execute the mdbook command to rebuild the docs. For Chinese, whose two-letter ISO-639 code is zh:

    mdbook build docs -d build
    MDBOOK_BOOK__LANGUAGE=zh mdbook build docs -d build/zh
    mv docs/build/zh/html docs/build/html/zh
    python3 -m http.server --directory docs/build/html --bind 127.0.0.1 8080
    
  6. If everything looks good, commit XX.po and open a pull request on GitHub. Other changed files should be omitted from the pull request.

ord's People

Contributors

andrewtoth avatar arik-so avatar bingryan avatar casey avatar cberner avatar cryptoni9n avatar cryptoquick avatar drjinglee avatar elocremarc avatar felipelincoln avatar gmart7t2 avatar jeremyrubin avatar ldiego08 avatar lifofifox avatar losingle avatar lugondev avatar mj10021 avatar ordinaho avatar oxsaturn avatar phorkish avatar raphjaph avatar rot13maxi avatar soenkehahn avatar terror avatar twosatsmaxi avatar veryordinally avatar vuittont60 avatar windsok avatar ynohtna92 avatar zhiqiangxu avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

ord's Issues

Document use for stablecoins

A stablecoin issuer could agree to redeem certain satoshis for the value of $1 + 1 satoshi, thus issuing a stablecoin that could transact on base-chain bitcoin.

Test underpaying subsidy

Test that ord list produces the correct results even when a block destroys fees and underpays the subsidy.

Bug: Handle multiple atoms per coin

My code assumes that there's at most one atom per coin, in particular:

let mut atoms: BTreeMap<OutPoint, u64> = BTreeMap::new();

It should be:

let mut atoms: BTreeMap<OutPoint, Vec<u64>> = BTreeMap::new();

Make integration tests more specific

Currently, we use the same chain and transactions for all integration tests. Instead, use whatever chain and txs are needed for that specific test.

Current name traits assigns short names to coins that will most likely never move

The current name trait produces short names at lower block heights. As a result, the shortest names were created in early blocks.

This is unfortunate, since it's very likely that early blocks will never move, so early names will never be available for use.

We could:

  • Make it so that names start at the longest name possible, and get shorter as time goes on.
  • Number satoshis in reverse, so that the first satoshi mined has number 2099999997690000 and the last satoshi to be mined has number 0. This is weird, but it fixes the problem for all traits, so the name trait doesn't have to be a special case.
  • Just ignore the problem, and resign ourselves to the fact that short names are probably locked forever.

Ordinal-aware wallet derivation paths

Strongly suggest that ordinal-aware HD wallets use different derivation paths for all outputs, and to never mix ordinal-aware outputs and transactions with non-ordinal aware outputs and transactions.

Perhaps even come up with and suggest the use of a specific distinct derivation path.

Mutable traits

  • Path: List of block heights in which a satoshi was moved, including the block in which it was mined
  • Wealth: Value of the largest utxo a satoshi was contained by

Document use in lightning

Two lightning nodes could open a channel using only ordinals which were pledged to be NFTs and transact using it via lightning. You could thus transact with stablecoins, or even a wrapped alt-coin on lightning.

Allow invalid ordinals

I think statically checking that ordinals are in range is a bad idea. Ordinal range of post-subsidy blocks can't be represented, it makes the code messier, it forces starting_ordinal functions to return an option, etc. I think I should just do validation on the edges but not in the code.

Also make last name a and not ``, so that we can represent the ending range of names as [,)

Scarcity

Atoms, as currently devised, are extremely scarce. Currently, it works out to around 1 atom per 26 bitcoin. This is good and bad. Atoms are scarce, so more likely to have and hold value. However, their scarcity means that, if you need an atom to mint an NFT, for example, you might have to pay a lot for the privilage.

Alternatives:

  • One atom per coinbase output. Allows more atoms to be created if there's more demand.
  • Fractionalization schemes.
  • Multiple tiers of atoms. Tier 0: One per block. Tier 1: One per coinbase output. Tier 2: One per transaction output of every mined transaction. T0 is scarce and inelastic supply. T0 is less scarce, and production can respond to demand. T2: Absurd amounts, more than anyone could every one.

One possibility is that every output of every transaction of every block creates an atom. Numbered BLOCK.TRANSACTION.OUTPUT. If output is zero it can be omitted. If transaction and output are both zero, they can be omitted. What emerges is something similar to Urbit's address space, where shorter identifiers are scarcer and more valuable.

Project name, number names

sat-tracker isn't the most exciting name, and talking about "satoshi numbers" isn't great either. I'd like to come up with a slightly sexy name for the project, and a way of referring unambiguously to a satoshi's number. For the former, I have no idea, but for the latter I was thinking about calling them "ordinals" or "ordinal numbers". An ordinal number denotes the position of an item within a set, so seems perfect for this, which identifies the order in which a satoshi was created. The word "ordinal" isn't used anywhere else in Bitcoin, so it isn't ambiguous.

Name for project

The idea has been simplified and now atoms aren't a thing, it's all based on numbering and tracking individual satoshis. So bitcoin-atoms isn't the best name.

The project consists of:

  • a BIP for numbering and tracking satoshis
  • a command-line tool for tracking satoshis

Reconsider descending numbering

I'm thinking that descending numbering is possibly a mistake. It's intended to fix the problem that satoshis with short, desirable names were mined in early blocks, which presumably won't ever move. We could fix this by defining the naming scheme to go from long to short, instead of reversing the numbering of all satoshis. I think this would be better, since ascending numbers feel more natural and are easier to explain. Using ascending numbers would mean that desirable numbers, like single-digit satoshis, were mined in the genesis block, which is still unfortunate. However, it might be worth the additional simplicity. After all, what's short doesn't really matter, what matters is what's rare, and short, low numbers will still be rare, they'll just be longer than otherwise. Additionally, it'll be exciting to see if early blocks suddenly move, which would lower the floor on the length of sat numbers.

Trait ideas

  • Character trait: Map atom to a unicode character.
  • Unlucky: all 13s
  • Cursed: ???
  • Blessed: ???
  • Blast crater: the satoshis adjacent to the one which would have been which was destroyed in block 124724

Figure out best transfer algorithm

The current algorithm is biased towards assigning atoms to later outputs in a transaction.

For example, if transaction has as single input worth 10 carrying atom 0:

# inputs and outputs are `[satoshis, atoms]`
inputs = [[10, 0]] # one input carrying 10 sats and atom 0
outputs = [[5], [5, 0]] # an output carrying 5 sats and no atoms, and an output carrying 5 sats and atom 0

It seems like it would be a bit more "natural" to favor earlier outputs.

The ideal transfer mechanism would, when naively used, distribute atoms proportionally to satoshis, but could be abused to move atoms around more intentionally.

It could use something which is usually randomly distributed, like the last digit of the satoshi value of outputs, to perturb the allocation.

Figure out transmutation algorithm

It should be possible to commit a 256 bit value to an atom. It's okay if this has happened to atoms historically, and random values have been committed to them, since you can also undo transmutation.

NFT signing

  • It should be possible to sign NFTs with a hardware wallet
  • It should be possible to derive different signing identities from the same hardware wallet seed, that can be used for different purposes

Atom Traits

Atoms have traits. There are many traits, some interesting, some not. More traits are being discovered at a breakneck pace.

Many traits are based on an atom's sire, the block in which an atom was crated. Some traits are based on hosts, the coins that have carried a specific atom.

Discovered traits:

  • Domain: The sire's height
  • Order: The index of the block in which the transaction creating the atom was created
  • Species: The index of the output in which the atom was created
  • Epoch: The sire's reward epoch
  • Parity: Whether the sire's height is even or odd
  • Difficulty: Sire's difficulty target
  • Overkill: Sire's difficulty target - sire's hash
  • Richness: The number of atoms moved in the sire in which the atom was mined
  • BDD: For each previous host, the number of bitcoin days destroyed when that host was destroyed, summed together
  • Worth: The highest value of all the hosts that the atom has been attached.
  • Path: The list of block heights in which an atom was moved.

Hypothesized traits:

  • Codepoint: Some mapping from serial number
  • The unicode codepoint of the atom. The mapping of atoms to codepoints is currently unknown. There are 16 planes, so there would be some mapping of domain, order, and species to plane and then codepoint. Many atoms would have an unallocated codepoint, which is fine.
  • Word: Given some list of words in a canonical order, it might be possible to associate a word with an atom. This would be hard. Could also have multiple words. This could be used as a username or a domain.

Discuss social legitimacy of NFTs

It isn't commonly articulated, but NFTs are judged based on social legitimacy, which is hard for people to grok.

If Bob mints an NFT using an original work of art, that NFT is highly legitimate, and may have value. If Bob mints an NFT with someone else's art without permission, that NFT is highly illegitimate.

Atoms are an attempt to create the most legitimate possible NFTs.

List command

sat-tracker list OUTPOINT should print the list of satoshis on particular output.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.