Rust Libraries

Tidecoin maintains Rust code for protocol data structures, hash functions, script validation experiments, YespowerTIDE hashing, and Falcon/FN-DSA work. The C++ node remains the consensus source of truth. Rust code is integration infrastructure unless a specific crate and version is documented as consensus equivalent to a Tidecoin Core release.

This page maps the Rust repositories and explains how to use them safely. It is not an API reference, and it does not replace node-backed validation for consensus-critical systems.

For exchange, wallet, explorer, and mining integrations, Rust libraries are most useful for parsing Tidecoin data, constructing transactions, checking addresses, running offline tooling, and validating local invariants before handing final state to Tidecoin Core.

Repository Map

Use Git dependencies or pinned commits unless a crate has a documented release policy. Record the exact repository commit in downstream integration notes.

rust-tidecoin

rust-tidecoin is the main Rust protocol workspace. It is the right starting point for explorers, indexers, wallets, offline transaction tools, address validators, and services that need Tidecoin-native parsing without shelling out to tidecoin-cli for every operation.

The workspace is layered:

Downstream applications should normally depend on the public tidecoin crate. Use lower crates only when the integration deliberately needs those boundaries, such as a validation engine, a no-std encoding layer, or a parity-test harness.

rust-yespower

rust-yespower exposes the Tidecoin pre-AuxPoW mining hash:

This crate is for pre-AuxPoW tools, test harnesses, research scripts, and legacy mining integrations. It is not the post-AuxPoW merged-mining path. After AuxPoW activation, Tidecoin block proof comes from a scrypt parent header plus an AuxPoW proof; see AuxPoW Integration.

The crate vendors the yespower C implementation and builds it through Cargo’s cc build pipeline. It does not run bindgen during normal builds.

tide-fn-dsa

tide-fn-dsa is Tidecoin’s Rust Falcon/FN-DSA compatibility repository. It is split into an umbrella crate and smaller component crates:

The repository tracks Falcon-family behavior and Tidecoin compatibility work. Do not assume future NIST FN-DSA naming or encoding changes are automatically Tidecoin consensus changes. Tidecoin wire compatibility is determined by the node, the active scheme registry, and the accepted public-key/signature encodings.

For wallet work, the important compatibility questions are:

• does generated key material match Tidecoin PQHD derivation expectations;
• does the public key use the scheme prefix expected by Tidecoin;
• does the signature encoding match the node’s verification path;
• does Falcon-512 legacy behavior match historical mainnet consensus;
• does Falcon-1024 behavior match the post-AuxPoW activation rules.

Integration Uses

Rust libraries are useful for:

• explorers;
• indexers;
• analytics tools;
• light clients;
• transaction construction;
• offline validation utilities;
• mining or proof-of-work tooling.

Do not use an out-of-tree Rust implementation as a substitute for consensus validation unless it is explicitly tested against the node and kept in lockstep with protocol changes.

Version And Release Discipline

For every Rust dependency, record:

• the Tidecoin Core commit or release it matches;
• the activated scheme set it supports;
• the address families it encodes and decodes;
• the test vectors it passes;
• whether it supports AuxPoW serialization;
• whether it is suitable for mainnet funds or only research/testing.

For production services, pin exact Git revisions or crate versions. Avoid floating branch dependencies in exchange, pool, explorer, or wallet builds.

Validation Boundary

Rust code can reject obviously invalid local input before RPC submission, but Tidecoin Core is still the arbiter for mempool admission, block validity, wallet policy, fee policy, and active-chain state. A robust integration uses Rust libraries for local construction and parsing, then uses Core RPCs such as testmempoolaccept, sendrawtransaction, getrawtransaction, and getblock to verify behavior against the live node.

The practical boundary is:

Minimum Test Expectations

Add regression vectors whenever the node changes a consensus-visible rule, address prefix, signature scheme, script flag, AuxPoW rule, or transaction serialization behavior.

Build And Test Commands

From the rust-tidecoin workspace:

cargo test --workspace
cargo clippy --workspace --all-targets

Node-backed parity tests may require a local Tidecoin Core checkout and explicit environment variables. Keep those tests separate from normal downstream builds; they are for maintainers and integration validation, not ordinary application startup.

From rust-yespower:

cargo test

From tide-fn-dsa:

cargo test --workspace

When Not To Use The Rust Crates

• Do not use them as the only validator for deposits or withdrawals.
• Do not use them to decide final block acceptance without Tidecoin Core.
• Do not enable dev-only node parity features in normal application builds.
• Do not assume a crate supports mainnet post-AuxPoW behavior unless that claim is tested and documented.
• Do not assume a Falcon/FN-DSA API is Tidecoin-wallet-compatible just because it can sign and verify messages internally.

Source Of Truth

See also: Repo Map, PQ Test Vectors, Build From Source, Protocol.