From 2be621406132ba034e6c9729e3f1fbd0e26bda4d Mon Sep 17 00:00:00 2001 From: DaniPopes <57450786+DaniPopes@users.noreply.github.com> Date: Fri, 2 Feb 2024 22:22:40 +0100 Subject: [PATCH] docs: update signer documentation (#180) --- crates/network/src/transaction/common.rs | 19 ++++++ crates/signer/README.md | 78 +++++++++++++----------- crates/signer/src/wallet/error.rs | 2 +- crates/signer/src/wallet/mnemonic.rs | 4 +- crates/signer/src/wallet/mod.rs | 2 + crates/signer/src/wallet/private_key.rs | 2 +- crates/signer/src/wallet/yubi.rs | 2 +- 7 files changed, 70 insertions(+), 39 deletions(-) diff --git a/crates/network/src/transaction/common.rs b/crates/network/src/transaction/common.rs index 42bf4d89486..45d637a655f 100644 --- a/crates/network/src/transaction/common.rs +++ b/crates/network/src/transaction/common.rs @@ -12,6 +12,25 @@ pub enum TxKind { Call(Address), } +impl From> for TxKind { + /// Creates a `TxKind::Call` with the `Some` address, `None` otherwise. + #[inline] + fn from(value: Option
) -> Self { + match value { + None => TxKind::Create, + Some(addr) => TxKind::Call(addr), + } + } +} + +impl From
for TxKind { + /// Creates a `TxKind::Call` with the given address. + #[inline] + fn from(value: Address) -> Self { + TxKind::Call(value) + } +} + impl TxKind { /// Returns the address of the contract that will be called or will receive the transfer. pub const fn to(self) -> Option
{ diff --git a/crates/signer/README.md b/crates/signer/README.md index 81a7718c45b..bb14922cb70 100644 --- a/crates/signer/README.md +++ b/crates/signer/README.md @@ -2,57 +2,65 @@ Ethereum signer abstraction. -You can implement the `Signer` trait to extend functionality to other signers -such as Hardware Security Modules, KMS etc. +You can implement the [`Signer`][Signer] trait to extend functionality to other signers +such as Hardware Security Modules, KMS etc. See [its documentation][Signer] for more. -Supported signers: -- [Private key](./src/wallet) -- [Ledger](./src/ledger) -- [Trezor](./src/trezor) +Signer implementations in this crate: +- [Private key](./src/wallet/private_key.rs) - [YubiHSM2](./src/wallet/yubi.rs) -- [AWS KMS](./src/aws) -## Examples - - +[Signer]: https://alloy-rs.github.io/alloy/alloy_signer/trait.Signer.html -// can also sign a message -let signature = wallet.sign_message("hello world").await?; -signature.verify("hello world", wallet.address()).unwrap(); -# Ok(()) -# } -``` ---> +## Examples Sign an Ethereum prefixed message ([EIP-712](https://eips.ethereum.org/EIPS/eip-712)): ```rust use alloy_signer::{LocalWallet, Signer, SignerSync}; -let message = "Some data"; +// Instantiate the wallet. let wallet = LocalWallet::random(); -// Sign the message +// Sign a message. +let message = "Some data"; let signature = wallet.sign_message_sync(message.as_bytes())?; -// Recover the signer from the message +// Recover the signer from the message. let recovered = signature.recover_address_from_msg(message)?; - assert_eq!(recovered, wallet.address()); # Ok::<_, Box>(()) ``` + +Sign a transaction: + +```rust +use alloy_consensus::TxLegacy; +use alloy_primitives::{U256, address, bytes}; +use alloy_signer::{LocalWallet, Signer, SignerSync}; + +// Instantiate the wallet. +let wallet = "dcf2cbdd171a21c480aa7f53d77f31bb102282b3ff099c78e3118b37348c72f7" + .parse::()?; + +// Create a transaction. +let mut tx = TxLegacy { + to: address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045").into(), + value: U256::from(1_000_000_000), + gas_limit: 2_000_000, + nonce: 0, + gas_price: 21_000_000_000, + input: bytes!(), + chain_id: Some(1), +}; + +// Sign it. +let signature = wallet.sign_transaction_sync(&mut tx)?; +# Ok::<_, Box>(()) +``` diff --git a/crates/signer/src/wallet/error.rs b/crates/signer/src/wallet/error.rs index f62dc2c7fba..4afee40c7f4 100644 --- a/crates/signer/src/wallet/error.rs +++ b/crates/signer/src/wallet/error.rs @@ -2,7 +2,7 @@ use alloy_primitives::hex; use k256::ecdsa; use thiserror::Error; -/// Error thrown by the Wallet module. +/// Error thrown by [`Wallet`](crate::Wallet). #[derive(Debug, Error)] pub enum WalletError { /// [`ecdsa`] error. diff --git a/crates/signer/src/wallet/mnemonic.rs b/crates/signer/src/wallet/mnemonic.rs index 2157c344b50..20793b72751 100644 --- a/crates/signer/src/wallet/mnemonic.rs +++ b/crates/signer/src/wallet/mnemonic.rs @@ -1,5 +1,7 @@ -//! Specific helper functions for creating/loading a mnemonic private key following BIP-39 +//! Specific helper functions for creating/loading a mnemonic private key following [BIP-39] //! specifications. +//! +//! [BIP-39]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki use crate::{utils::secret_key_to_address, Wallet, WalletError}; use coins_bip32::path::DerivationPath; diff --git a/crates/signer/src/wallet/mod.rs b/crates/signer/src/wallet/mod.rs index 6f42fa121b0..46b7af6de55 100644 --- a/crates/signer/src/wallet/mod.rs +++ b/crates/signer/src/wallet/mod.rs @@ -1,3 +1,5 @@ +//! In-memory (local) private key signer. + use crate::{Result, Signer, SignerSync}; use alloy_primitives::{Address, ChainId, Signature, B256}; use async_trait::async_trait; diff --git a/crates/signer/src/wallet/private_key.rs b/crates/signer/src/wallet/private_key.rs index f8da5c959fc..d5624e75c71 100644 --- a/crates/signer/src/wallet/private_key.rs +++ b/crates/signer/src/wallet/private_key.rs @@ -1,4 +1,4 @@ -//! Specific helper functions for loading an offline K256 Private Key stored on disk +//! [`k256`] wallet implementation. use super::{Wallet, WalletError}; use crate::utils::secret_key_to_address; diff --git a/crates/signer/src/wallet/yubi.rs b/crates/signer/src/wallet/yubi.rs index 6a02fe30f27..b6d81c7d1a7 100644 --- a/crates/signer/src/wallet/yubi.rs +++ b/crates/signer/src/wallet/yubi.rs @@ -1,4 +1,4 @@ -//! Helpers for creating wallets for YubiHSM2. +//! [YubiHSM2](yubihsm) wallet implementation. use super::Wallet; use crate::utils::raw_public_key_to_address;