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 litoshis with numismatic value, allowing them to be collected and traded as curios.
Ordinal numbers are serial numbers for litoshis, 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 litecoin 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:
-
Litecoin Core is not aware of inscriptions and does not perform sat control. Using
litecoin-cli
commands and RPC calls withord
wallets may lead to loss of inscriptions. -
ord wallet
commands automatically load theord
wallet given by the--wallet
option, which defaults to 'ord'. Keep in mind that after running anord wallet
command, anord
wallet may be loaded. -
Because
ord
has access to your litecoin 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://raw.githubusercontent.com/ynohtna92/ord-litecoin/master/install.sh | bash -s
Once ord
is installed, you should be able to run ord --version
on the
command line.
Building
On Debian and Ubuntu, ord
requires libssl-dev
when building from source:
sudo apt-get install libssl-dev
You'll also need Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
To build ord
from source:
git clone https://github.com/ynohtna92/ord-litecoin.git
cd ord-litecoin
cargo build --release
Once built, the ord
binary can be found at ./target/release/ord
.
ord
requires rustc
version 1.67.0 or later. Run rustc --version
to ensure you have this version. Run rustup update
to get the latest stable release.
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 test-bitcoincore-rpc.
Syncing
ord
requires a synced litecoind
node with -txindex
to build the index of
satoshi locations. ord
communicates with litecoind
via RPC.
If litecoind
is run locally by the same user, without additional
configuration, ord
should find it automatically by reading the .cookie
file
from litecoind
's datadir, and connecting using the default RPC port.
If litecoind
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.
Windows Compatibility
To prevent port exhaustion when running ord index
you should change the register values
below with the following steps:
- From the command prompt, run
regedit
. - Navigate to
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TCPIP\Parameters
. - Create a new key for
REG_DWORD
, and specify the nameMaxUserPort
. - Enter the decimal value
32768
. - Create a new key for
REG_DWORD
, and specify the nameTcpTimedWaitDelay
. - Type the minimum decimal value
30
(which is 0x0000001e in hexadecimal), if you have a newer system (Windows 8 or later) the minimum decimal value can be entered as2
. - Restart the workstation.
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-user foo --bitcoin-rpc-pass bar server
Using environment variables:
export ORD_BITCOIN_RPC_USER=foo
export ORD_BITCOIN_RPC_PASS=bar
ord server
Or in the config file:
bitcoin_rpc_user: foo
bitcoin_rpc_pass: 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
New Releases
Release commit messages use the following template:
Release x.y.z
- Bump version: x.y.z → x.y.z
- Update changelog
- Update dependencies
Translations
To translate the docs we use this mdBook i18n helper. So read through their usage guide to see the structure that translations should follow.
There are some other things to watch out for but feel free to just start a translation and open a PR. Have a look at this commit for an idea of what to do. A maintainer will also help you integrate it into our build system.
To align your translated version of the Handbook with reference to commit #2427, here are some guiding commands to assist you. It is assumed that your local environment is already well-configured with Python, Mdbook, mdBook i18n helper and that you've clone this repo.
- Run the following command to generate a new
pot
file, which is named asmessages.pot
:
MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}'
mdbook build -d po
- Run
msgmerge
wherexx.po
is your localized language version following the naming standard of ISO639-1. This process will update thepo
file with the most recent original version:
msgmerge --update po/xx.po po/messages.pot
-
Look for
#, fuzzy
. ThemdBook-i18n-helper
tool utilizes the"fuzzy"
tag to highlight sections that have been recently edited. You can proceed to perform the translation tasks by editing the"fuzzy"
part. -
Execute the
mdbook
command. A demonstration in Chinese (zh
) is given below:
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
- Upon verifying everything and ensuring all is in order, you can commit the modifications and progress to open a Pull Request (PR) on Github. (Note: Please ensure ONLY the 'xx.po' file is pushed, other files such as '.pot' or files ending in '~' are unnecessary and should NOT be included in the Pull Request.)