Crate sidestr_hitch

Expand description

Lightning-shaped payment-channel transactions for sidestr and Bitcoin-family testnets.

This is an attributed Rust port of lib/channel.mjs in Melvin Carvalho’s Hitch, at commit 62f8e39. Hitch is the Lightning construction without the Lightning network: two peers lock a coin in a 2-of-2 Taproot leaf, hold asymmetric revocable commitments, and update them off chain. Optional HTLC outputs add a preimage success path, an absolute timeout and a revocation path.

A commitment’s revocation key is a two-party key: the counterparty’s basepoint plus the owner’s per-state point (revocation_pub). The owner never holds its secret, so it cannot use its own revocation leaf; the counterparty learns the per-state secret when the state is revoked and then signs with revocation_key. Every announced point carries a proof of possession (pop_sign), so neither side can choose a point that cancels the other’s.

The transaction builders are paired with a pure peer state machine in protocol and the one-hop invoice decisions in route. Hosts provide relay transport, wallet funding, atomic snapshot storage, chain watches and broadcasting. Every builder supports both ordinary BIP 341 sighashes and Bitcoin Knots’ unified sighash used by txbt4. This is a channel kernel, not a Lightning node, and it does not speak to Lightning peers.

use bitcoin::hashes::Hash;
use bitcoin::secp256k1::{Keypair, SecretKey};
use bitcoin::{Amount, OutPoint, Txid};
use sidestr_core::block::secp;
use sidestr_hitch::{Balances, Channel, ChannelState, RevocationKeys, Side};

let key_a = SecretKey::from_slice(&[0x11; 32]).unwrap();
let key_b = SecretKey::from_slice(&[0x22; 32]).unwrap();
let pub_a = Keypair::from_secret_key(secp(), &key_a).x_only_public_key().0;
let pub_b = Keypair::from_secret_key(secp(), &key_b).x_only_public_key().0;
let channel = Channel::new(
    pub_a,
    pub_b,
    OutPoint { txid: Txid::all_zeros(), vout: 0 },
    Amount::from_sat(100_000),
    Amount::from_sat(300),
    6,
).unwrap();
let state = ChannelState {
    balances: Balances { a: Amount::from_sat(60_000), b: Amount::from_sat(40_000) },
    revocation: RevocationKeys { a: pub_a, b: pub_b },
    htlcs: vec![],
};
let commitment = channel.commitment(1, Side::A, &state).unwrap();
assert_eq!(commitment.local_value, Amount::from_sat(59_700));
assert_eq!(commitment.remote_value, Amount::from_sat(40_000));

Modules§

protocol: Hitch’s channel protocol (lib/peer.mjs) as a pure, sans-IO state machine.
route: Hitch’s one-hop invoices and HTLC routing (lib/route.mjs) as a pure decision engine.

Structs§

Balances: The two free balances in a channel state. HTLC values are separate.
Channel: A funded channel and its invariant parameters.
ChannelState: Free balances, revocation keys and outstanding HTLCs at one state number.
Commitment: One peer’s fully derived commitment transaction for a state.
CommitmentHtlc: An HTLC after its exact output index and scripts have been derived for a particular commitment owner.
FundingScript: Hitch’s 2-of-2 funding output.
Htlc: An HTLC carried by a channel state.
HtlcClaim: Output and witness choices for an HTLC claim transaction.
HtlcScript: A three-path HTLC output in one commitment transaction.
HtlcScriptArgs: Arguments needed to derive one commitment owner’s HTLC scripts.
LeafSignature: A 65-byte tapscript signature: BIP-340 signature followed by its explicit sighash type (0x01 or Knots’ 0x21).
LeafSpend: One Taproot leaf and the control block that proves it to its output.
PopSignature: A 64-byte BIP 340 proof of possession of a revocation secret, carried as 128 lower-case hex characters on Hitch’s wire.
RevocationKeys: The revocation public key each owner put into this state.
ToLocalScript: A revocable delayed output in one commitment transaction.

Enums§

Error: An error while deriving scripts, building a state or signing a spend.
HtlcClaimPath: Which leaf claims an HTLC output.
OutputKind: An output’s role in a commitment transaction.
Side: One of the two channel peers. A is the funder and pays channel fees.
SweepPath: Which to_local leaf a sweep uses.

Constants§

DEFAULT_DELAY: Hitch’s default relative delay, in blocks.
DEFAULT_FEE: Hitch’s default per-transaction channel fee, in satoshis.
DUST: Outputs below this value are omitted from commitments, as in Hitch.
MAX_DELAY: The longest relative delay Hitch accepts.
MAX_EXPIRY: Values below this are block heights rather than timestamps in nLockTime.
MAX_FEE: The largest per-transaction channel fee Hitch accepts, in satoshis.
MIN_DELAY: The shortest relative delay Hitch accepts.
MIN_FEE: The smallest per-transaction channel fee Hitch accepts, in satoshis.

Functions§

claim_htlc: Spend one HTLC output through its success, timeout or revocation leaf.
even_secret: Negate secret when its public point has an odd y coordinate, so the result’s point is the even lift of the same x-only key. This is Hitch’s evenSecret.
funding_script: Construct the 2-of-2 funding script. Keys are sorted lexicographically in the leaf, independently of their A/B protocol roles.
htlc_script: Construct the success, timeout and revocation leaves for an HTLC. The tree is branch(branch(success, timeout), revocation).
internal_key: Derive Hitch’s fixed unspendable internal key: BIP 341’s H tweaked by tagged_hash("hitch/nums", "hitch").
key_path_spend: Spend a plain to_remote output by its literal x-only key path.
pop_sign: Prove possession of a revocation secret: a BIP 340 signature by secret over tagged_hash("hitch/pop", context || point). Hitch’s context is "<channel id>/<owner role>/<base or state number>".
pop_verify: Check a proof of possession made by pop_sign for point in context. Malformed signatures verify as false.
preimage_in: The payment preimage revealed by a spend of an HTLC output, if any 32-byte witness item hashes to payment_hash under SHA-256. This is Hitch’s preimageIn, used to carry a preimage the counterparty revealed on the chain back upstream.
revocation_key: The secret of a two-party revocation key: even(basepoint_secret) + even(per_state_secret) mod n. This is Hitch’s revocationKey; it signs the revocation leaves of a commitment whose public key is revocation_pub.
revocation_pub: The public half of a two-party revocation key: lift_x(point) + even(scalar)·G, as an x-only key. This is Hitch’s revocationPub.
script_path_sighash: Compute a tapscript signature hash and its explicit wire hash type.
sign_leaf: Sign one tapscript leaf with an explicit hash type byte.
sweep_to_local: Spend a commitment’s to_local output through its delayed or revocation leaf and install the complete witness.
to_local_script: Construct the owner’s delayed leaf and the counterparty’s revocation leaf, rooted as branch(delayed, revocation).
to_remote_script: A direct key-path output using Hitch’s x-only channel key literally.
verify_leaf_signature: Verify one tapscript signature under the same family rules used to sign.

Type Aliases§

Result: Result type returned by this crate.