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!
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.
Security
The ord server explorer hosts untrusted HTML and JavaScript. This creates
potential security vulnerabilities, including cross-site scripting and spoofing
attacks. You are solely responsible for understanding and mitigating these
attacks. See the documentation for more details.
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:
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:
MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}'
mdbook build -d po
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
Untranslated sections are marked with #, fuzzy in XX.po. Edit the
msgstr string with the translated text.
Execute the mdbook command to rebuild the docs. For Chinese, whose
two-letter ISO-639 code is zh: