This crate provides core cryptographic primitives and message hashing utilities for StarkNet-based applications, with a focus on interoperability and off-chain message construction. The code is designed to be called from other languages (such as Python or JavaScript) and provides a set of Rust functions and types for working with StarkNet signatures, domain separation, and message hashing.
This is the main entry point of the library. It provides:
-
Key Derivation and Signing
grind_key: Deterministically derives a StarkNet-compatible private key from a seed using SHA-256 and modular reduction.get_private_key_from_eth_signature: Extracts a private key from an Ethereum signature, using thegrind_keyfunction.sign_message: Signs a message using StarkNet ECDSA and returns aStarkSignaturestruct.
-
Message Hashing Functions
get_order_hash: Computes the hash for an order message, given all order parameters as strings.get_transfer_hash: Computes the hash for a transfer message, given all transfer parameters as strings.get_withdrawal_hash: Computes the hash for a withdrawal message, given all withdrawal parameters as strings.get_withdraw_and_stake_hash: Computes the hash for a withdraw-and-stake message, given all its parameters as strings.vaultandbeneficiaryare EVM addresses and must fit in 160 bits.get_withdraw_and_stake_eip712_typed_data: Returns theeth_signTypedData_v4JSON document the withdraw-and-stake beneficiary's EVM wallet signs. Takes the same withdraw-and-stake inputs asget_withdraw_and_stake_hash, plus the EVM chain id and the settlement contract (verifying_contract_hex) of the EIP-712 domain.get_withdraw_and_stake_eip712_hash: Returns the 32-byte EIP-712 digest (hex) of that same document, for checking a wallet's signature.
-
Types
StarkSignature: Holds ther,s, andvcomponents of a StarkNet ECDSA signature.
-
Testing
- Comprehensive unit tests for key derivation, signing, and message hash computation.
EIP-712 typed data for messages an EVM wallet signs, encoded by alloy. A withdraw-and-stake must also be signed by its beneficiary's EVM wallet:
domain: the zk engine's domain (Perpetuals/1, EVM chain id, settlement contract). Both the chain id and the contract must be set.signing_hashandtyped_data: the digest and theeth_signTypedData_v4document for any message declared in the module'ssol!block.WithdrawAndStakeArgs::eip712_message,eip712_hashandeip712_typed_data: the beneficiary'sWithdrawAndStakemessage over the same fields the position owner signs.
To add an EVM-signed message, declare it in the sol! block (deriving serde::Serialize) and pass it to signing_hash and typed_data.
This module defines the core data structures and hashing logic for StarkNet off-chain messages:
-
Traits
Hashable: For types that can be hashed with a Poseidon hash and a selector.OffChainMessage: For types that represent off-chain messages and can be hashed with domain separation and a public key.
-
Domain and Message Types
StarknetDomain: Represents the domain for message separation (name, version, chain_id, revision).AssetId,PositionId,AssetAmount,Timestamp: Basic types for message construction.Order,TransferArgs,WithdrawalArgs,WithdrawAndStakeArgs: Main message types for orders, transfers, withdrawals, and withdraw-and-stake.
-
Hash Implementations
- Each message type implements
Hashableand provides a unique selector and hashing logic using the Poseidon hash function.
- Each message type implements
-
Constants
SEPOLIA_DOMAIN: A pre-defined domain for the Sepolia testnet.
-
Testing
- Unit tests for selectors, hashing, and message hash computation for all message types.
- Hashing and Signing:
Use the functions inlib.rsto derive keys, sign messages, and compute message hashes for StarkNet off-chain protocols. - Extending Message Types:
Implement theHashableandOffChainMessagetraits for new message types as needed. - Interoperability:
All public functions are designed to accept string arguments for easy FFI or WASM integration.
use rust_crypto_lib_base::{get_order_hash, sign_message, get_private_key_from_eth_signature};
// Compute an order hash
let hash = get_order_hash(
"1".to_string(), "0x2".to_string(), "100".to_string(), "0x1".to_string(),
"-156".to_string(), "0x1".to_string(), "74".to_string(), "100".to_string(),
"123".to_string(), "0x...".to_string(), "Perpetuals".to_string(), "v0".to_string(),
"SN_SEPOLIA".to_string(), "1".to_string()
)?;
// Sign a message
let private_key = get_private_key_from_eth_signature("0x...")?;
let signature = sign_message(&hash, &private_key)?;