Ordinalsプロジェクトから学ぶRustプログラミング完全ガイド

# rustupをインストール
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# パスを通す
source $HOME/.cargo/env

# バージョン確認
rustc --version
cargo --version

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

# デバッグビルド
cargo build

# リリースビルド（最適化あり）
cargo build --release

# テストの実行
cargo test

// 不変の変数（再代入不可）
let x = 5;
// x = 6;  // コンパイルエラー！

// 可変の変数（再代入可能）
let mut y = 5;
y = 6;  // OK

// 引数と戻り値の型は必須
fn add(a: i32, b: i32) -> i32 {
    a + b  // セミコロンなしで式を返す
}

// 戻り値がない場合（Unit型 ()を返す）
fn greet(name: &str) {
    println!("Hello, {}!", name);
}

pub fn main() {
    env_logger::init();

    ctrlc::set_handler(move || {
        if SHUTTING_DOWN.fetch_or(true, atomic::Ordering::Relaxed) {
            process::exit(1);
        }

        eprintln!("Shutting down gracefully. Press <CTRL-C> again to shutdown immediately.");

        LISTENERS
            .lock()
            .unwrap()
            .iter()
            .for_each(|handle| handle.graceful_shutdown(Some(Duration::from_millis(100))));

        gracefully_shut_down_indexer();
    })
    .expect("Error setting <CTRL-C> handler");

    let args = Arguments::parse();

    let format = args.options.format;

    match args.run() {
        Err(err) => {
            eprintln!("error: {err}");
            // エラーハンドリング...
            process::exit(1);
        }
        Ok(output) => {
            if let Some(output) = output {
                output.print(format.unwrap_or_default());
            }
            gracefully_shut_down_indexer();
        }
    }
}

match args.run() {
    Err(err) => {
        eprintln!("error: {err}");
        process::exit(1);
    }
    Ok(output) => {
        if let Some(output) = output {
            output.print(format.unwrap_or_default());
        }
    }
}

// matchを使う場合
match output {
    Some(value) => println!("{}", value),
    None => {},  // 何もしないケースも書く必要がある
}

// if letを使う場合（より簡潔）
if let Some(value) = output {
    println!("{}", value);
}

use {
    self::{
        arguments::Arguments,
        blocktime::Blocktime,
        // ...
    },
    anyhow::{Context, Error, anyhow, bail, ensure},
    bitcoin::{
        Amount, Block, KnownHrp, Network, OutPoint, // ...
    },
    std::{
        collections::{BTreeMap, BTreeSet, HashSet},
        env,
        // ...
    },
};

1 BTC = 100,000,000 satoshi

最初のブロック（ジェネシスブロック）の報酬:
  sat 0 ~ sat 4,999,999,999 (50億sat = 50 BTC)

2番目のブロックの報酬:
  sat 5,000,000,000 ~ sat 9,999,999,999

...以降、マイニングされた順に番号が付与される

use {super::*, std::num::ParseFloatError};

#[derive(Copy, Clone, Eq, PartialEq, Debug, Display, Ord, PartialOrd, Deserialize, Serialize)]
#[serde(transparent)]
pub struct Sat(pub u64);

impl Sat {
    pub const LAST: Self = Self(Self::SUPPLY - 1);
    pub const SUPPLY: u64 = 2099999997690000;
    // ...
}

type Sat = number & { readonly __brand: unique symbol };

#[derive(Copy, Clone, Eq, PartialEq, Debug, Display, Ord, PartialOrd, Deserialize, Serialize)]
pub struct Sat(pub u64);

impl Sat {
    pub const LAST: Self = Self(Self::SUPPLY - 1);
    pub const SUPPLY: u64 = 2099999997690000;
}

報酬は4年ごとに半減:
  Epoch 0: 50 BTC/ブロック × 210,000ブロック = 10,500,000 BTC
  Epoch 1: 25 BTC/ブロック × 210,000ブロック =  5,250,000 BTC
  Epoch 2: 12.5 BTC/ブロック × 210,000ブロック = 2,625,000 BTC
  ...
  合計: 20,999,999.9769 BTC (= 2,099,999,997,690,000 sat)

impl Sat {
    // メソッド定義
}

impl Sat {
    pub fn n(self) -> u64 {
        self.0  // タプル構造体の中身にアクセス
    }

    pub fn height(self) -> Height {
        self.epoch().starting_height()
            + u32::try_from(self.epoch_position() / self.epoch().subsidy()).unwrap()
    }
}

pub fn height(self) -> Height {
    self.epoch().starting_height()
        + u32::try_from(self.epoch_position() / self.epoch().subsidy()).unwrap()
}

pub fn cycle(self) -> u32 {
    Epoch::from(self).0 / CYCLE_EPOCHS
}

pub fn subsidy(self) -> u64 {
    if self < Self::FIRST_POST_SUBSIDY {
        (50 * COIN_VALUE) >> self.0
    } else {
        0
    }
}

50 * COIN_VALUE >> 0  // = 5,000,000,000 (50 BTC)
50 * COIN_VALUE >> 1  // = 2,500,000,000 (25 BTC) - 1回目の半減
50 * COIN_VALUE >> 2  // = 1,250,000,000 (12.5 BTC) - 2回目の半減

pub fn rarity(self) -> Rarity {
    self.into()  // Sat -> Rarity への変換
}

// 使用例
let sat = Sat(0);
let rarity = sat.rarity();  // Mythic

#[derive(
    Clone, Copy, Debug, DeserializeFromStr, Eq, Hash, PartialEq, PartialOrd, SerializeDisplay,
)]
pub enum Rarity {
    Common,
    Uncommon,
    Rare,
    Epic,
    Legendary,
    Mythic,
}

pub fn supply(self) -> u64 {
    match self {
        Self::Common => 2_099_999_990_760_000,
        Self::Uncommon => 6_926_535,
        Self::Rare => 3_432,
        Self::Epic => 27,
        Self::Legendary => 5,
        Self::Mythic => 1,
    }
}

impl From<Sat> for Rarity {
    fn from(sat: Sat) -> Self {
        let Degree {
            hour,
            minute,
            second,
            third,
        } = sat.degree();

        if hour == 0 && minute == 0 && second == 0 && third == 0 {
            Self::Mythic
        } else if minute == 0 && second == 0 && third == 0 {
            Self::Legendary
        } else if minute == 0 && third == 0 {
            Self::Epic
        } else if second == 0 && third == 0 {
            Self::Rare
        } else if third == 0 {
            Self::Uncommon
        } else {
            Self::Common
        }
    }
}

let Degree { hour, minute, second, third } = sat.degree();

const { hour, minute, second, third } = sat.degree();

impl Display for Rarity {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        write!(
            f,
            "{}",
            match self {
                Self::Common => "common",
                Self::Uncommon => "uncommon",
                Self::Rare => "rare",
                Self::Epic => "epic",
                Self::Legendary => "legendary",
                Self::Mythic => "mythic",
            }
        )
    }
}

interface Printable {
  print(): void;
}
class Document implements Printable { ... }

trait Printable {
    fn print(&self);
}
impl Printable for Document { ... }

// Fromを実装すると
impl From<Sat> for Epoch { ... }

// 以下のように使える
let epoch = Epoch::from(sat);  // From
let epoch: Epoch = sat.into();  // Into（自動的に実装される）

impl From<Sat> for Epoch {
    fn from(sat: Sat) -> Self {
        if sat < Self::STARTING_SATS[1] {
            Epoch(0)
        } else if sat < Self::STARTING_SATS[2] {
            Epoch(1)
        } else if sat < Self::STARTING_SATS[3] {
            Epoch(2)
        }
        // ... 各エポックの境界値でチェック
        else {
            Epoch(33)
        }
    }
}

impl FromStr for Rarity {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "common" => Ok(Self::Common),
            "uncommon" => Ok(Self::Uncommon),
            "rare" => Ok(Self::Rare),
            "epic" => Ok(Self::Epic),
            "legendary" => Ok(Self::Legendary),
            "mythic" => Ok(Self::Mythic),
            _ => Err(format!("invalid rarity `{s}`")),
        }
    }
}

let rarity: Rarity = "rare".parse().unwrap();  // Ok(Rarity::Rare)
let rarity: Rarity = "invalid".parse();        // Err("invalid rarity `invalid`")

impl Display for Rarity {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        write!(f, "{}", match self {
            Self::Common => "common",
            // ...
        })
    }
}

// 使用例
let rarity = Rarity::Rare;
println!("{}", rarity);      // "rare"
let s = rarity.to_string();  // "rare"

impl TryFrom<u8> for Rarity {
    type Error = u8;

    fn try_from(rarity: u8) -> Result<Self, u8> {
        match rarity {
            0 => Ok(Self::Common),
            1 => Ok(Self::Uncommon),
            2 => Ok(Self::Rare),
            3 => Ok(Self::Epic),
            4 => Ok(Self::Legendary),
            5 => Ok(Self::Mythic),
            n => Err(n),  // 無効な値はエラー
        }
    }
}

let rarity = Rarity::try_from(2)?;  // Ok(Rarity::Rare)
let rarity = Rarity::try_from(99);  // Err(99)

// TypeScript
function find(id: number): User | null { ... }
function parse(s: string): User { throw new Error(...); }

// Rust
fn find(id: u32) -> Option<User> { ... }
fn parse(s: &str) -> Result<User, ParseError> { ... }

// ?を使わない場合
fn read_file() -> Result<String, io::Error> {
    let file = match File::open("hello.txt") {
        Ok(f) => f,
        Err(e) => return Err(e),
    };
    // ...
}

// ?を使う場合
fn read_file() -> Result<String, io::Error> {
    let file = File::open("hello.txt")?;  // エラーなら即座にreturn Err
    // ...
}

pub fn encode_to_vec(mut n: u128, v: &mut Vec<u8>) {
    while n >> 7 > 0 {
        v.push(n.to_le_bytes()[0] | 0b1000_0000);
        n >>= 7;
    }
    v.push(n.to_le_bytes()[0]);
}

pub fn decode(buffer: &[u8]) -> Result<(u128, usize), Error> {
    let mut n = 0u128;

    for (i, &byte) in buffer.iter().enumerate() {
        if i > 18 {
            return Err(Error::Overlong);
        }

        let value = u128::from(byte) & 0b0111_1111;

        if i == 18 && value & 0b0111_1100 != 0 {
            return Err(Error::Overflow);
        }

        n |= value << (7 * i);

        if byte & 0b1000_0000 == 0 {
            return Ok((n, i + 1));
        }
    }

    Err(Error::Unterminated)
}

#[derive(PartialEq, Debug)]
pub enum Error {
    Overlong,     // 長すぎる
    Overflow,     // オーバーフロー
    Unterminated, // 終端がない
}

impl Display for Error {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::Overlong => write!(f, "too long"),
            Self::Overflow => write!(f, "overflow"),
            Self::Unterminated => write!(f, "unterminated"),
        }
    }
}

impl std::error::Error for Error {}

// map: 値がある場合に変換
let x: Option<i32> = Some(5);
let y: Option<String> = x.map(|n| n.to_string());  // Some("5")

// and_then: 値がある場合に別のOption/Resultを返す関数を適用
let x: Option<&str> = Some("42");
let y: Option<i32> = x.and_then(|s| s.parse().ok());  // Some(42)

// unwrap_or: 値がない場合のデフォルト値
let x: Option<i32> = None;
let y: i32 = x.unwrap_or(0);  // 0

pub fn pointer(&self) -> Option<u64> {
    let value = self.pointer.as_ref()?;  // Noneなら早期リターン

    if value.iter().skip(8).copied().any(|byte| byte != 0) {
        return None;
    }

    let pointer = [
        value.first().copied().unwrap_or(0),
        value.get(1).copied().unwrap_or(0),
        value.get(2).copied().unwrap_or(0),
        // ...
    ];

    Some(u64::from_le_bytes(pointer))
}

let s1 = String::from("hello");
let s2 = s1;  // 所有権がs1からs2に移動（move）
// println!("{}", s1);  // コンパイルエラー！s1はもう使えない
println!("{}", s2);  // OK

// 不変の借用（&T）- 複数同時に可能
let s = String::from("hello");
let r1 = &s;  // 借用
let r2 = &s;  // 複数OK
println!("{}, {}", r1, r2);

// 可変の借用（&mut T）- 1つだけ
let mut s = String::from("hello");
let r = &mut s;
r.push_str(", world");
println!("{}", r);

#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Eq, Default)]
pub struct Inscription {
    pub body: Option<Vec<u8>>,
    pub content_encoding: Option<Vec<u8>>,
    pub content_type: Option<Vec<u8>>,
    pub delegate: Option<Vec<u8>>,
    pub duplicate_field: bool,
    pub incomplete_field: bool,
    pub metadata: Option<Vec<u8>>,
    pub metaprotocol: Option<Vec<u8>>,
    pub parents: Vec<Vec<u8>>,
    pub pointer: Option<Vec<u8>>,
    pub properties: Option<Vec<u8>>,
    pub property_encoding: Option<Vec<u8>>,
    pub rune: Option<Vec<u8>>,
    pub unrecognized_even_field: bool,
}

pub fn body(&self) -> Option<&[u8]> {
    Some(self.body.as_ref()?)
}

pub fn into_body(self) -> Option<Vec<u8>> {
    self.body
}

pub fn content_length(&self) -> Option<usize> {
    Some(self.body()?.len())
}

// ライフタイム注釈なし（単純なケース）
fn first_word(s: &str) -> &str {
    &s[..s.find(' ').unwrap_or(s.len())]
}

// ライフタイム注釈あり（複雑なケース）
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

fn properties_cbor(&self) -> Option<Cow<[u8]>> {
    let value = self.properties.as_deref()?;

    if let Some(encoding) = &self.property_encoding {
        if encoding != BROTLI.as_bytes() {
            return None;
        }

        // 圧縮データを展開 → 新しいVecを作成
        let mut value = Vec::new();
        // ... decompression ...
        Some(Cow::Owned(value))  // 所有
    } else {
        Some(Cow::Borrowed(value))  // 借用
    }
}

pub mod api;
pub mod arguments;
mod blocktime;
pub mod chain;
pub mod decimal;
mod deserialize_from_str;
mod error;
mod fee_rate;
mod fund_raw_transaction;
pub mod index;
mod inscriptions;
// ...

// 完全にプライベート（デフォルト）
fn private_fn() {}

// 同じクレート内で公開
pub(crate) fn crate_fn() {}

// 親モジュールまで公開
pub(super) fn super_fn() {}

// 完全に公開
pub fn public_fn() {}

pub use self::{
    chain::Chain,
    fee_rate::FeeRate,
    index::{Index, RuneEntry},
    inscriptions::{Envelope, Inscription, InscriptionId, ParsedEnvelope, RawEnvelope},
    object::Object,
    options::Options,
    properties::{Attributes, Item, Properties, Trait, Traits},
    wallet::transaction_builder::{Target, TransactionBuilder},
};

[workspace]
members = [".", "crates/*"]

ord/
├── Cargo.toml          # ワークスペースルート
├── src/                # メインクレート
│   └── lib.rs
├── crates/             # サブクレート
│   ├── ordinals/       # Ordinal理論の実装
│   │   └── src/
│   │       ├── sat.rs
│   │       ├── rarity.rs
│   │       └── ...
│   └── mockcore/       # テスト用モック
└── tests/              # 統合テスト

[package]
name = "ord"
description = "◉ Ordinal wallet and block explorer"
version = "0.24.2"
autotests = false
autobins = false

authors.workspace = true
edition.workspace = true
homepage.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true

[workspace.package]
authors = ["The Ord Maintainers"]
edition = "2024"
homepage = "https://github.com/ordinals/ord"
license = "CC0-1.0"
repository = "https://github.com/ordinals/ord"
rust-version = "1.89.0"

#[derive(Default, PartialEq, Clone, Serialize, Deserialize, Debug, Eq)]
pub struct Envelope<T> {
    pub input: u32,
    pub offset: u32,
    pub payload: T,
    pub pushnum: bool,
    pub stutter: bool,
}

// 具体的な型を指定して使用
pub type RawEnvelope = Envelope<Vec<Vec<u8>>>;
pub type ParsedEnvelope = Envelope<Inscription>;

interface Envelope<T> {
    input: number;
    offset: number;
    payload: T;
    pushnum: boolean;
    stutter: boolean;
}

type RawEnvelope = Envelope<number[][]>;
type ParsedEnvelope = Envelope<Inscription>;

// Displayを実装している型のみ受け付ける
fn print<T: Display>(value: T) {
    println!("{}", value);
}

// 複数のトレイト境界
fn process<T: Display + Clone>(value: T) {
    let copy = value.clone();
    println!("{}", copy);
}

fn complex_function<T, U>(t: T, u: U)
where
    T: Display + Clone,
    U: Debug + Default,
{
    // ...
}

let v = vec![1, 2, 3, 4, 5];

// イテレータを作成（まだ何も実行されない）
let iter = v.iter();

// 値を消費する時に初めて評価される
for x in iter {
    println!("{}", x);
}

// 基本形
let add = |a, b| a + b;
let result = add(1, 2);  // 3

// 型注釈付き
let add: fn(i32, i32) -> i32 = |a, b| a + b;

// 複数行
let process = |x| {
    let y = x * 2;
    y + 1
};

impl ParsedEnvelope {
    pub fn from_transaction(transaction: &Transaction) -> Vec<Self> {
        RawEnvelope::from_transaction(transaction)
            .into_iter()
            .map(|envelope| envelope.into())
            .collect()
    }
}

function fromTransaction(transaction: Transaction): ParsedEnvelope[] {
    return RawEnvelope.fromTransaction(transaction)
        .map(envelope => envelope.into());
}

impl From<RawEnvelope> for ParsedEnvelope {
    fn from(envelope: RawEnvelope) -> Self {
        let body = envelope
            .payload
            .iter()
            .enumerate()
            .position(|(i, push)| i % 2 == 0 && push.is_empty());

        let mut fields: BTreeMap<&[u8], Vec<&[u8]>> = BTreeMap::new();

        for item in envelope.payload[..body.unwrap_or(envelope.payload.len())].chunks(2) {
            match item {
                [key, value] => fields.entry(key).or_default().push(value),
                _ => incomplete_field = true,
            }
        }

        // ...
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn n() {
        assert_eq!(Sat(1).n(), 1);
        assert_eq!(Sat(100).n(), 100);
    }

    #[test]
    fn height() {
        assert_eq!(Sat(0).height(), 0);
        assert_eq!(Sat(1).height(), 0);
        assert_eq!(Sat(Epoch(0).subsidy()).height(), 1);
        // ...
    }
}

#[cfg(test)]
mod tests {
    // テストコードはテスト時のみコンパイルされる
}

assert!(condition);                    // 条件が真であることを確認
assert_eq!(left, right);               // 等値を確認
assert_ne!(left, right);               // 不等を確認
assert!(condition, "error message");   // メッセージ付き

#[test]
fn common() {
    #[track_caller]
    fn case(n: u64) {
        assert_eq!(Sat(n).common(), Sat(n).rarity() == Rarity::Common);
    }

    case(0);
    case(1);
    case(50 * COIN_VALUE - 1);
    case(50 * COIN_VALUE);
    case(50 * COIN_VALUE + 1);
    case(2067187500000000 - 1);
    case(2067187500000000);
    case(2067187500000000 + 1);
}

プロジェクト構造:
ord/
├── src/
│   └── lib.rs          # #[cfg(test)] mod tests { ... }
├── tests/              # 統合テスト
│   └── lib.rs
└── crates/
    └── mockcore/       # テスト用モッククレート

// 実際のBitcoin Coreを起動せずにテスト可能
let mock = mockcore::spawn();
let client = mock.client();
// テストを実行

use std::sync::Arc;

let data = Arc::new(vec![1, 2, 3]);

// 別スレッドにクローンを渡す
let data_clone = Arc::clone(&data);
std::thread::spawn(move || {
    println!("{:?}", data_clone);
});

static SHUTTING_DOWN: AtomicBool = AtomicBool::new(false);
static LISTENERS: Mutex<Vec<axum_server::Handle>> = Mutex::new(Vec::new());
static INDEXER: Mutex<Option<thread::JoinHandle<()>>> = Mutex::new(None);

pub fn cancel_shutdown() {
    SHUTTING_DOWN.store(false, atomic::Ordering::Relaxed);
}

pub fn shut_down() {
    SHUTTING_DOWN.store(true, atomic::Ordering::Relaxed);
}

// Send: 別スレッドに所有権を移動できる
// Sync: 複数スレッドから参照できる

// Arc<Mutex<T>> は Send + Sync
// 生ポインタは !Send + !Sync（スレッド安全ではない）

use bitcoin::{
    Amount, Block, Network, OutPoint, Transaction, Txid,
    blockdata::constants::{DIFFCHANGE_INTERVAL, SUBSIDY_HALVING_INTERVAL},
};

let amount = Amount::from_sat(1000);
let network = Network::Bitcoin;  // Mainnet

use clap::Parser;

#[derive(Parser)]
struct Args {
    #[arg(short, long)]
    verbose: bool,

    #[arg(short, long, default_value = "mainnet")]
    network: String,
}

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
    age: u32,
}

let json = serde_json::to_string(&user)?;
let user: User = serde_json::from_str(&json)?;

[dependencies]
# 基本的な依存関係
anyhow = { version = "1.0.90", features = ["backtrace"] }

# ワークスペースから継承
bitcoin.workspace = true

# ローカルパス依存
ordinals = { version = "0.0.15", path = "crates/ordinals" }

[dev-dependencies]
# テスト時のみの依存関係
mockcore = { path = "crates/mockcore" }
pretty_assertions.workspace = true

bitcoin = { version = "0.32.5", features = ["rand"] }

# リポジトリをフォーク＆クローン
git clone https://github.com/YOUR_USERNAME/ord.git
cd ord

# ビルド確認
cargo build

# テスト実行
cargo test

# フォーマットチェック
cargo fmt -- --check

# 自動フォーマット
cargo fmt --all

# 警告をエラーとして扱う（CIと同じ設定）
cargo clippy --all --all-targets -- --deny warnings

ci: clippy forbid
  cargo fmt -- --check
  cargo test --all
  cargo test --all -- --ignored

# CIと同じチェックを実行
just ci