diff --git a/docs/pages/wallet-security/account-abstraction.mdx b/docs/pages/wallet-security/account-abstraction.mdx index 63c3f7da6..f19cf75a5 100644 --- a/docs/pages/wallet-security/account-abstraction.mdx +++ b/docs/pages/wallet-security/account-abstraction.mdx @@ -1,6 +1,6 @@ --- title: "Account Abstraction Wallets | Security Alliance" -description: "ERC-4337 Account Abstraction wallets: social recovery, gas sponsorship, batch transactions, and customizable security policies. Eliminate single points of failure like seed phrase loss." +description: "ERC-4337 Account Abstraction wallets: social recovery, gas sponsorship, batch transactions, and customizable security policies" tags: - Engineer/Developer - Security Specialist @@ -10,6 +10,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: Account abstraction adds programmable controls and recovery options—and new attack surfaces. +> Threat-model guardians, modules, and session keys before relying on them. + ## User Profile Advanced users, developers, and organizations interested in programmable security, customizable transaction rules, and @@ -85,6 +90,15 @@ new one without having to move all assets to a new wallet address. recovery action. This method allows guardians to produce a valid signature through a distributed computation using their individual shares, without ever reconstructing a single master key on any device. +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Using EIP-7702](/wallet-security/signing-and-verification/verifying-7702): the delegation path that brings this to + existing EOAs +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): the established alternative to + guardian-based recovery +- [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337): the specification behind UserOperations and bundlers + --- diff --git a/docs/pages/wallet-security/cold-vs-hot-wallet.mdx b/docs/pages/wallet-security/cold-vs-hot-wallet.mdx index ace50aaa9..4d7bddafc 100644 --- a/docs/pages/wallet-security/cold-vs-hot-wallet.mdx +++ b/docs/pages/wallet-security/cold-vs-hot-wallet.mdx @@ -1,6 +1,6 @@ --- title: "Cold Vs Hot Wallet | Security Alliance" -description: "Compare cold vs hot wallets: security trade-offs, use cases, and risk profiles. Hardware wallets, paper wallets, and air-gapped devices vs browser extensions and mobile wallets." +description: "Compare cold vs hot wallets: security trade-offs, use cases, and risk profiles. Hardware wallets, paper wallets. The primary distinction between wallet" tags: - Engineer/Developer - Security Specialist @@ -10,6 +10,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect, patrickalphac] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: Hot wallets maximize convenience and online exposure; cold wallets reduce remote attack surface +> at the cost of operational friction. Match fund tier to exposure. + The primary distinction between wallet types is their connectivity to the internet. This factor dictates their security threat model, risk profile, and ideal use cases. @@ -91,6 +96,15 @@ Regardless of the type, non-custodial wallets place the full burden of security - **Supply Chain Attacks**: Be cautious of both software and hardware integrity. Always download wallet software from official sources and purchase hardware wallets directly from the manufacturer to avoid receiving a tampered device. +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [For Beginners & Small Balances](/wallet-security/for-beginners-and-small-balances): a hot-wallet-first setup done + safely +- [For Intermediates & Medium Balances](/wallet-security/intermediates-and-medium-funds): adding cold storage as + balances grow +- [Seed Phrase Management](/wallet-security/seed-phrase-management): the backup practices both wallet types depend on + --- diff --git a/docs/pages/wallet-security/custodial-vs-non-custodial.mdx b/docs/pages/wallet-security/custodial-vs-non-custodial.mdx index d727deaea..075a6521b 100644 --- a/docs/pages/wallet-security/custodial-vs-non-custodial.mdx +++ b/docs/pages/wallet-security/custodial-vs-non-custodial.mdx @@ -10,6 +10,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: Custody is who holds the private keys. Custodial services trade self-sovereignty for recovery +> convenience and counterparty risk; non-custodial flips that tradeoff. + The distinction between custodial and non-custodial wallets centers on who controls the private keys. This control directly impacts ownership, security responsibility, and the ability to interact with the web3 ecosystem. @@ -75,6 +80,13 @@ to undertake the responsibility of self-custody. | **Primary Risk** | Counterparty Risk, Centralization | User Error, Loss of Keys | | **Use Case** | New Users, Trading on CEX, Convenience | Full Control, dApp Use, Long-Term Storage | +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Cold vs. Hot Wallets](/wallet-security/cold-vs-hot-wallet): the other axis to decide alongside custody +- [Seed Phrase Management](/wallet-security/seed-phrase-management): the responsibility that comes with self-custody +- [Account Abstraction Wallets](/wallet-security/account-abstraction): recovery options without handing over the keys + --- diff --git a/docs/pages/wallet-security/encumbered-wallets.mdx b/docs/pages/wallet-security/encumbered-wallets.mdx index e686d76a2..aebd01166 100644 --- a/docs/pages/wallet-security/encumbered-wallets.mdx +++ b/docs/pages/wallet-security/encumbered-wallets.mdx @@ -1,6 +1,6 @@ --- title: "TEE-based Encumbered Wallets | Security Alliance" -description: "TEE-based encumbered wallets: implement cross-chain security policies using Trusted Execution Environments. Fine-grained permissions, time-bounded access, and compliance features for any blockchain." +description: "TEE-based encumbered wallets: implement cross-chain security policies using Trusted Execution Environments. Fine-grained permissions, time-bounded access" tags: - Engineer/Developer - Security Specialist @@ -10,7 +10,8 @@ contributors: users: [njelich] - role: reviewed users: [pinalikefruit] - + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -20,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: TEE and encumbrance-based wallets shift trust into hardware and policy constraints. Validate the +> threat model and failure modes; they are not automatic trustlessness. + ## User Profile Advanced users, developers, and organizations wanting to implement fine-grained security policies, that don't want to @@ -168,6 +172,15 @@ solutions, as even root or physical access to the host system cannot compromise * Aublin, P.-L., Mahhouk, M., & Kapitza, R. (n.d.). Towards TEEs with Large Secure Memory and Integrity Protection Against HW Attacks [IIJ Innovation Institute, TU Braunschweig](https://www.ibr.cs.tu-bs.de/bib/xml/aublin2022scalableSGX.html) +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Account Abstraction Wallets](/wallet-security/account-abstraction): the on-chain route to programmable policy +- [Custodial vs. Non-Custodial Wallets](/wallet-security/custodial-vs-non-custodial): the trust model TEE custody sits + between +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): distributing trust across signers + instead of hardware + --- diff --git a/docs/pages/wallet-security/for-beginners-and-small-balances.mdx b/docs/pages/wallet-security/for-beginners-and-small-balances.mdx index 71e86c7ff..65c32c144 100644 --- a/docs/pages/wallet-security/for-beginners-and-small-balances.mdx +++ b/docs/pages/wallet-security/for-beginners-and-small-balances.mdx @@ -1,6 +1,6 @@ --- title: "Wallets for Beginners & Small Balances | SEAL" -description: "Hot wallet setup guide for beginners with small balances. Select browser extension, mobile, or desktop wallets. Evaluate open-source code and use Wallet Scrutiny for security assessment." +description: "Hot wallet setup guide for beginners with small balances. Select browser extension, mobile, or desktop wallets. A user with foundational web3 knowledge" tags: - Engineer/Developer - Security Specialist @@ -9,6 +9,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -18,6 +20,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: Small balances still need unique secrets and phishing resistance. Start simple, but keep habits +> that scale: unique seeds, careful signing, offline backups. + ## User Profile A user with foundational web3 knowledge who is actively learning and interacting with dApps. The asset value is @@ -60,6 +65,15 @@ on specific criteria such as transaction clarity, protection against known threa Using these tools can provide valuable data points to help you assess a wallet's security posture and make an informed decision. +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Seed Phrase Management](/wallet-security/seed-phrase-management): the one habit worth getting right from day one +- [Smart Contract Interaction Security](/wallet-security/smart-contract-interaction-security): approvals and signing + mistakes that cost beginners funds +- [For Intermediates & Medium Balances](/wallet-security/intermediates-and-medium-funds): what to add as your balance + grows + --- diff --git a/docs/pages/wallet-security/hardware-wallets.mdx b/docs/pages/wallet-security/hardware-wallets.mdx index 63f2a8e7f..413d595da 100644 --- a/docs/pages/wallet-security/hardware-wallets.mdx +++ b/docs/pages/wallet-security/hardware-wallets.mdx @@ -1 +1,37 @@ +--- +title: "Hardware Wallets | SEAL" +description: "Stub page for hardware wallets under Wallet Security. Expand with practical custody and verification guidance. Placeholder page pending expert expansion of controls an..." +tags: + - Engineer/Developer + - Security Specialist +contributors: + - role: wrote + users: [] + - role: reviewed + users: [] + - role: fact-checked + users: [] +--- + +import { TagList, AttributionList, ContributeFooter } from '../../../components' + # Hardware Wallets + + + + +> 🔑 **Key Takeaway**: This page is a placeholder until filled with dedicated guidance. + +Stub/in progress. Help contribute or expand this page. See the [Wallet Security overview](/wallet-security/overview) +and related cold/hot, seed phrase, and signing pages for production guidance. + +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [For Intermediates & Medium Balances](/wallet-security/intermediates-and-medium-funds): hardware wallet selection and + initial setup in practice +- [Seed Phrase Management](/wallet-security/seed-phrase-management): protecting the backup the device generates + +--- + + diff --git a/docs/pages/wallet-security/intermediates-and-medium-funds.mdx b/docs/pages/wallet-security/intermediates-and-medium-funds.mdx index 501c14526..57a166e34 100644 --- a/docs/pages/wallet-security/intermediates-and-medium-funds.mdx +++ b/docs/pages/wallet-security/intermediates-and-medium-funds.mdx @@ -1,6 +1,6 @@ --- title: "Wallets for Intermediates & Medium Funds | SEAL" -description: "Hardware wallet guide for intermediate users with medium balances. Select devices with secure elements, verify supply chain integrity, configure PINs, and maintain backup devices." +description: "Hardware wallet guide for intermediate users with medium balances. Select devices with secure elements, verify supply chain integrity, configure PINs" tags: - Engineer/Developer - Security Specialist @@ -9,6 +9,8 @@ contributors: users: [pinalikefruit, isaac, geoffrey, louis, pablo, dickson, auditware] - role: reviewed users: [Coinspect, engn33r] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -18,6 +20,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: As balances grow, add hardware isolation, better backup design, and stricter signing habits—do +> not keep intermediate funds on the same hot path as everyday spending wallets. + ## User Profile An intermediate user who is comfortable with web3 interactions and is now managing a significant, but not life-altering, @@ -115,6 +120,15 @@ Maintain a backup hardware wallet to avoid needing to access your seed phrase if * Store backup securely * Monthly verification that backup device functions correctly +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Seed Phrase Management](/wallet-security/seed-phrase-management): backup design for the devices set up here +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the stricter signing habits + this tier requires +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): the next step once a single signer + is too much risk + --- diff --git a/docs/pages/wallet-security/overview.mdx b/docs/pages/wallet-security/overview.mdx index 9e1cf24d4..f7de7f436 100644 --- a/docs/pages/wallet-security/overview.mdx +++ b/docs/pages/wallet-security/overview.mdx @@ -1,11 +1,17 @@ --- title: "Wallet Security | Security Alliance" -description: "Wallet Security Framework: Secure digital assets with hot/cold wallets, multisig best practices, transaction verification, seed phrase management, and account abstraction." +description: "Wallet security for Web3: custody models, hot/cold tradeoffs, tiered setups, multisig and AA, signing verification, seed phrases, and interaction hygiene." +tags: + - Engineer/Developer + - Security Specialist + - Operations & Strategy contributors: - role: wrote users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -15,52 +21,49 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -In cryptocurrency, the security of digital assets is directly tied to how control over the funds is protected. This -section provides a technical deep-dive into wallet security, covering the range from fundamental concepts to advanced -practices for safeguarding assets against theft, loss, and unauthorized access. +> 🔑 **Key Takeaway**: Wallet security is control of keys and verification of every signature. Hardware and multisig +> fail if users sign attacker-controlled calldata blindly. -The goal is to move beyond introductory concepts and provide actionable, technical knowledge for securely managing -crypto assets. +In cryptocurrency, asset security is tied to how control over funds is protected. This framework goes from ownership +models and wallet types to signing verification, seed-phrase custody, and safer smart contract interaction. -## Table of Contents +## What this framework covers -- [Custodial vs Non-Custodial](/wallet-security/custodial-vs-non-custodial) - Comparing custodial and non-custodial -wallet solutions. -- [Cold vs Hot Wallet](/wallet-security/cold-vs-hot-wallet) - Understanding the security trade-offs of online and -offline wallets. -- [Wallets For Beginners & Small Balances](/wallet-security/for-beginners-and-small-balances) - Recommended setups for -users with non-critical funds. -- [Wallets For Intermediates & Medium Funds](/wallet-security/intermediates-and-medium-funds) - Security upgrades for -users with significant assets. -- [Multisig Wallets For Advanced Users & High Funds](/wallet-security/secure-multisig-best-practices) - Best practices -for setting up and managing multisig wallets. -- [Account Abstraction Wallets](/wallet-security/account-abstraction) - Exploring the security features of smart -contract wallets. -- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification) - An overview of secure -transaction signing and verification. - - [Verifying Standard Transactions (EOA)](/wallet-security/signing-and-verification/verifying-standard-transactions) - - How to safely verify transactions from standard wallets. - - [Multisig Signing Process](/wallet-security/signing-and-verification/secure-multisig-signing-process) - Detailed - guide for secure multisig transaction signing. - - [Using EIP-7702](/wallet-security/signing-and-verification/verifying-7702) - Enabling smart contract features for - EOAs and mitigating new risks. -- [Seed Phrase Management](/wallet-security/seed-phrase-management) - Best practices for securing your seed phrase. -- [Tools & Resources](/wallet-security/tools-and-resources) - A curated list of security tools and resources. +1. [Custodial vs Non-Custodial](/wallet-security/custodial-vs-non-custodial): who holds keys and what risk that creates. +2. [Cold vs Hot Wallet](/wallet-security/cold-vs-hot-wallet): online convenience versus offline isolation tradeoffs. +3. [Wallets for Beginners and Small Balances](/wallet-security/for-beginners-and-small-balances): lighter setups for lower + stakes. +4. [Wallets for Intermediates and Medium Funds](/wallet-security/intermediates-and-medium-funds): upgrades as value grows. +5. [Multisig Wallets for Advanced Users and High Funds](/wallet-security/secure-multisig-best-practices): high-value + multi-signer design. +6. [Account Abstraction Wallets](/wallet-security/account-abstraction): smart-account features and new risk surface. +7. [TEE-based Encumbered Wallets](/wallet-security/encumbered-wallets): encumbered/TEE-oriented models and caveats. +8. [Signing and Verification](/wallet-security/signing-and-verification/signing-verification): never sign blindly. + - [Verifying Standard Transactions (EOA)](/wallet-security/signing-and-verification/verifying-standard-transactions) + - [Multisig Signing Process](/wallet-security/signing-and-verification/secure-multisig-signing-process) + - [Safe Multisig: Step-by-Step Verification](/wallet-security/signing-and-verification/secure-multisig-safe-verification) + - [Squads Multisig: Step-by-Step Verification](/wallet-security/signing-and-verification/secure-multisig-squads-verification) + - [Using EIP-7702](/wallet-security/signing-and-verification/verifying-7702) +9. [Smart Contract Interaction Security](/wallet-security/smart-contract-interaction-security): addresses, approvals, and + simulation before interact. +10. [Seed Phrase Management](/wallet-security/seed-phrase-management): offline custody and emergency handling. +11. [Tools and Resources](/wallet-security/tools-and-resources): curated verification and training tools. -In this section you can learn: +## Related frameworks -- Explore wallet fundamentals, analyzing the security trade-offs of hot vs. cold wallets and the ownership implications -of custodial vs. non-custodial models. -- Receive guidance on choosing the right wallet for your threat model, from basic setups to advanced configurations like - Multisignature (Multisig) and Account Abstraction wallets. -- Master transaction verification techniques, from basic smart contract interactions to the advanced verification. -- Implement security best practices for private key and seed phrase management. +- [Multisig for Protocols](/multisig-for-protocols/overview): protocol treasury and organizational multisig ops +- [OpSec](/opsec/overview): device and operator hygiene around keys +- [Front-End Web App](/front-end-web-app/overview): client compromise can rewrite what wallets sign +- [ENS](/ens/overview): name resolution integrity on send destinations +- [Physical Security](/physical-security/overview): seed and device physical risks +- [Incident Management](/incident-management/overview): response after suspected key compromise -Mastering wallet security is a critical skill for any developer, user, or organization operating in the web3 ecosystem. +## Further Reading -![security](https://github.com/security-alliance/frameworks/assets/84518844/12e2cba3-f69e-4fde-85f1-8a235b9808af) +See [Tools and Resources](/wallet-security/tools-and-resources). Classic related prose: +[xkcd 538](https://xkcd.com/538/) on physical coercion of crypto holders. -[xkcd](https://xkcd.com/538/) +![security](https://github.com/security-alliance/frameworks/assets/84518844/12e2cba3-f69e-4fde-85f1-8a235b9808af) --- diff --git a/docs/pages/wallet-security/secure-multisig-best-practices.mdx b/docs/pages/wallet-security/secure-multisig-best-practices.mdx index 3b7d7601b..7c432fd6f 100644 --- a/docs/pages/wallet-security/secure-multisig-best-practices.mdx +++ b/docs/pages/wallet-security/secure-multisig-best-practices.mdx @@ -1,6 +1,6 @@ --- title: "Secure Multisig Best Practices | SEAL" -description: "Multisig best practices: M-of-N thresholds, signer distribution, hardware wallet requirements, communication protocols, timelock enforcement, and disaster recovery planning for high-value assets." +description: "Multisig best practices: M-of-N thresholds, signer distribution, hardware wallet requirements, communication protocols, timelock enforcement" tags: - Security Specialist - Operations & Strategy @@ -10,7 +10,8 @@ contributors: users: [engn33r, pinalikefruit, isaac, geoffrey, louis, pablo, dickson, auditware] - role: reviewed users: [Coinspect] - + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -20,8 +21,11 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> Guidance for designing, operating, and auditing high-assurance multisigs. Use this as your single source for baseline -> rules, setup guidance, and daily operations. +> 🔑 **Key Takeaway**: Multisig raises the bar only when signers, thresholds, devices, and verification procedures are +> independent and rehearsed. A poorly run multisig is theater. + +Guidance for designing, operating, and auditing high-assurance multisigs. Use this as your single source for baseline +rules, setup guidance, and daily operations. ## Who This Is For @@ -254,7 +258,7 @@ Safe. - If a new Safe appears in your dashboard that you did not create or expect, **do not interact with it** - Use your verified address book to confirm any Safe address before transacting -## Contract-Level Security +### Contract-Level Security - **Invariant Enforcement:** Design contracts to enforce invariants and expected state changes such as token balance changes, ownership and administration, and proxy implementation addresses. Ensure contracts automatically revert @@ -272,6 +276,14 @@ For detailed configuration guidance, see Some ideas were borrowed from the [EF's multisig SOP notes](https://notes.ethereum.org/@fredrik/multisig-sop) and [Manifold Finance multisig best practices](https://hackmd.io/@manifoldx/multisig-best-practices). +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Verifying Multisig Transactions](/wallet-security/signing-and-verification/secure-multisig-signing-process): the + per-signer verification these rules assume +- [Multisig for Protocols](/multisig-for-protocols/overview): running a multisig as an organization, with runbooks +- [Treasury Operations](/treasury-operations/overview): classification and controls for the funds being protected + --- diff --git a/docs/pages/wallet-security/seed-phrase-management.mdx b/docs/pages/wallet-security/seed-phrase-management.mdx index fca73850a..b0f4c6b65 100644 --- a/docs/pages/wallet-security/seed-phrase-management.mdx +++ b/docs/pages/wallet-security/seed-phrase-management.mdx @@ -1,6 +1,6 @@ --- title: "Seed Phrase Management | Security Alliance" -description: "Secure seed phrase management: physical written copies, metal backups, and 3-piece splitting strategies. Emergency access plans, tamper-evident bags, and prohibited digital storage practices." +description: "Secure seed phrase management: physical written copies, metal backups, and 3-piece splitting strategies. Emergency access plans, tamper-evident bags" tags: - Engineer/Developer - Security Specialist @@ -10,6 +10,8 @@ contributors: users: [pinalikefruit, isaac, geoffrey, louis, pablo, dickson] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: The seed phrase is complete wallet control. Keep it offline, treat any digital exposure as full +> compromise, and move funds if exposure is even suspected. + ## Private Key & Seed Phrase Management The **seed phrase** (or mnemonic phrase) is the master key to a non-custodial wallet, granting complete control over all @@ -214,4 +219,14 @@ both pieces to reconstruct seed immediately, then change all security settings." Remember: Your seed phrase security is the foundation of multisig security. Take time to implement proper storage procedures appropriate for your risk level. +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Cold vs. Hot Wallets](/wallet-security/cold-vs-hot-wallet): matching storage exposure to the value being backed up +- [Wallet and Key Architecture](/physical-security/coercion-and-duress/wallet-and-key-architecture): designing key + layout for coercion scenarios +- [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki): the mnemonic standard these phrases follow + +--- + diff --git a/docs/pages/wallet-security/signing-and-verification/secure-multisig-safe-verification.mdx b/docs/pages/wallet-security/signing-and-verification/secure-multisig-safe-verification.mdx index 64bba9f08..2203af749 100644 --- a/docs/pages/wallet-security/signing-and-verification/secure-multisig-safe-verification.mdx +++ b/docs/pages/wallet-security/signing-and-verification/secure-multisig-safe-verification.mdx @@ -1,6 +1,6 @@ --- title: "Safe Multisig Verification | SEAL" -description: "Safe multisig transaction verification: hash verification using CLI tools or OpenZeppelin Safe Utils, Tenderly simulations, calldata review, and nested Safe approval flows." +description: "Safe multisig transaction verification: hash verification using CLI tools or OpenZeppelin Safe Utils, Tenderly simulations, calldata review" tags: - Engineer/Developer - Security Specialist @@ -10,6 +10,8 @@ contributors: users: [isaac, geoffrey, louis, pablo, dickson] - role: reviewed users: [pinalikefruit, engn33r, ElliotFriedman] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../../componen +> 🔑 **Key Takeaway**: Safe verification requires matching transaction hashes and decoded intent across independent +> channels before any signature. + Hash verification protects against UI compromise attacks where malicious transactions are injected into the signing flow. The goal is to ensure that what you see in the UI matches what your hardware wallet actually signs. @@ -62,13 +67,15 @@ for details. Please see the [Tools & Resources](/wallet-security/tools-and-resources) page for a list of recommended tools. -## 1) Transaction Preparation +## Verification Procedure + +### 1) Transaction Preparation - Use delegated proposer (recommended) - Ensure the transaction is proposed in the Safe API - Record Safe address, network, nonce -## 2) Simulation Testing +### 2) Simulation Testing - Run Tenderly simulation from Safe UI; verify expected events and transfers - If using a timelock, expect a staged transaction event rather than execution @@ -87,9 +94,9 @@ Manual simulation (when needed): Note: For complex batch transactions that include a delegateCall to multisend, manual simulations may not be feasible. -## 3) Hash & Calldata Verification +### 3) Hash & Calldata Verification -**Using CLI tool:** +#### Using the CLI Tool ```bash ./safe_hashes.sh --network [NETWORK] --address [SAFE_ADDRESS] --nonce [NONCE] @@ -103,24 +110,19 @@ However, if you also verify the calldata output by the tool, you can be sure you in interactive mode the tool does not decode the calldata, so it's important to perform the calldata verification in step 5. -### Using web UI (OpenZeppelin Safe Utils) +#### Using the Web UI (OpenZeppelin Safe Utils) 1. Navigate to OpenZeppelin Safe Utils 2. Enter Safe address (checksummed) 3. Select network and enter nonce 4. Review generated hashes and decoded calldata -Important: Both tools require checksummed addresses: - -### Checksummed address examples +Important: Both tools require checksummed addresses. - ✅ Correct: `0xA79C6968E3c75aE4eF388370d1f142720D498fEC` - ❌ Incorrect: `0xa79c6968e3c75ae4ef388370d1f142720d498fec` -- Interactive mode note: In interactive mode the CLI does not decode calldata; be sure to perform the calldata - verification in step 5. - -## 4) Hash Comparison +### 4) Hash Comparison - Message Hash on tools must match hardware wallet display - Domain Hash ensures correct Safe @@ -129,13 +131,13 @@ Important: Both tools require checksummed addresses: compromised. When signing, verify the **entire** hash displayed on your hardware wallet, not just the first and last few characters. -## 5) Calldata Review +### 5) Calldata Review Hash verification confirms you are signing the right transaction (the one that was proposed), but the hash alone does not tell you what the transaction actually does. You need to decode the calldata to understand the on-chain action. Never sign a transaction you do not understand. -### How Calldata Works +#### How Calldata Works EVM calldata consists of: @@ -147,7 +149,7 @@ EVM calldata consists of: For batch transactions using MultiSend, the calldata contains multiple packed transactions. Each must be individually decoded and reviewed. -### Decoding Steps +#### Decoding Steps 1. Copy the calldata from the Safe UI or from the hash verification tool 2. Paste into a decoder (e.g., SwissKnife Calldata Decoder, Foundry `cast decode-calldata`) @@ -155,7 +157,7 @@ decoded and reviewed. 4. For protocol-specific functions, consider building internal decoding tooling tailored to your contracts for human-readable output -### Common Red Flags +#### Common Red Flags - **`DELEGATECALL` (operation type 1)**: Gives the target contract full control over the Safe's storage. Should only appear when the target is a known, audited module. @@ -178,17 +180,20 @@ decoded and reviewed. Signers should not all use identical tools. Cross-verify results between multiple tools (CLI and web) for critical operations. -## Special Cases: Nested Safes +### Special Cases: Nested Safes - Use `--nested-safe-address` and `--nested-safe-nonce` to verify approveHash flows ---- +## Further Reading -## Related Documents +- [Verifying Multisig Transactions](/wallet-security/signing-and-verification/secure-multisig-signing-process): the + two-phase process this walkthrough implements +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): signer and threshold design behind + the signing flow +- [Backup Signing & Infrastructure](/multisig-for-protocols/backup-signing-and-infrastructure): fallback paths when the + usual signing route is unavailable +- [Emergency Procedures](/multisig-for-protocols/emergency-procedures): what to do when verification reveals a problem -- [Hardware Wallet Setup](/wallet-security/intermediates-and-medium-funds) -- [Backup Signing & Infrastructure](/multisig-for-protocols/backup-signing-and-infrastructure) -- [Emergency Procedures](/multisig-for-protocols/emergency-procedures) -- [Tools & Resources](/wallet-security/tools-and-resources) +--- diff --git a/docs/pages/wallet-security/signing-and-verification/secure-multisig-signing-process.mdx b/docs/pages/wallet-security/signing-and-verification/secure-multisig-signing-process.mdx index 8342713a2..628274beb 100644 --- a/docs/pages/wallet-security/signing-and-verification/secure-multisig-signing-process.mdx +++ b/docs/pages/wallet-security/signing-and-verification/secure-multisig-signing-process.mdx @@ -1,6 +1,6 @@ --- title: "Secure Multisig Signing Process | SEAL" -description: "Verify multisig transactions in two phases: EIP-712 off-chain message signing and on-chain execTransaction execution. Compare hashes, decode calldata, and use transaction simulators." +description: "Verify multisig transactions in two phases: EIP-712 off-chain message signing and on-chain execTransaction execution. Skipping hash and intent checks" tags: - Security Specialist - Operations & Strategy @@ -10,6 +10,8 @@ contributors: users: [engn33r,pinalikefruit, isaac, geoffrey, louis, pablo, dickson, auditware] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../../components' @@ -19,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../../componen +> 🔑 **Key Takeaway**: Multisig signing needs a coordinated, independent verification path for every signer. Skipping +> hash and intent checks is how shared treasuries get drained. + The security of a multisig wallet relies on each signer independently verifying what they are signing. A compromised web interface could present a legitimate-looking transaction while tricking a hardware wallet into signing a malicious one. @@ -111,6 +116,17 @@ the network. When using a timelock, simulations may show the staging event rather than actual execution. Inspect the staged payload and verify cancellation/execution roles and parameters before proceeding. +## Further Reading + +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the principles this process + applies +- [Safe Multisig Verification](/wallet-security/signing-and-verification/secure-multisig-safe-verification): the + step-by-step EVM walkthrough +- [Squads Multisig Verification](/wallet-security/signing-and-verification/secure-multisig-squads-verification): the + Solana equivalent +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): signer, threshold, and device + design behind these steps + --- diff --git a/docs/pages/wallet-security/signing-and-verification/secure-multisig-squads-verification.mdx b/docs/pages/wallet-security/signing-and-verification/secure-multisig-squads-verification.mdx index 69070ac10..4ea840a31 100644 --- a/docs/pages/wallet-security/signing-and-verification/secure-multisig-squads-verification.mdx +++ b/docs/pages/wallet-security/signing-and-verification/secure-multisig-squads-verification.mdx @@ -1,6 +1,6 @@ --- title: "Squads Multisig Verification | SEAL" -description: "Squads multisig verification on Solana: decode SOL transfers, USDS transfers, and configuration changes. Interpret instruction data bytes and verify through Solana explorer." +description: "Squads multisig verification on Solana: decode SOL transfers, USDS transfers, and configuration changes. Interpret instruction data bytes and verify through" tags: - Engineer/Developer - Security Specialist @@ -10,6 +10,8 @@ contributors: users: [isaac, geoffrey, louis, pablo, dickson] - role: reviewed users: [pinalikefruit, engn33r] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../../components' @@ -22,6 +24,9 @@ cross-verify with team members. +> 🔑 **Key Takeaway**: Squads multisig verification follows the same principle as Safe: independently verify the +> proposal payload and hashes on trusted paths before signing. + ## Solana vs. EVM: Key Differences for Multisig Security Solana multisigs operate differently from EVM-based Safes in several important ways: @@ -132,4 +137,16 @@ Simulation does NOT seem to work for configuration changes, but we have another - Execute after collecting all signatures - Once all signatures are collected, execute the transaction. +## Further Reading + +- [Verifying Multisig Transactions](/wallet-security/signing-and-verification/secure-multisig-signing-process): the + two-phase process this walkthrough implements +- [Safe Multisig Verification](/wallet-security/signing-and-verification/secure-multisig-safe-verification): the EVM + counterpart, with more mature tooling +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): signer and threshold design behind + the signing flow +- [Squads documentation](https://docs.squads.so/): program behavior and proposal structure reference + +--- + diff --git a/docs/pages/wallet-security/signing-and-verification/signing-verification.mdx b/docs/pages/wallet-security/signing-and-verification/signing-verification.mdx index 73481dc03..ae500e0f8 100644 --- a/docs/pages/wallet-security/signing-and-verification/signing-verification.mdx +++ b/docs/pages/wallet-security/signing-and-verification/signing-verification.mdx @@ -1,6 +1,6 @@ --- title: "Signing Verification | Security Alliance" -description: "Transaction verification guide: verify origin, smart contract address, function parameters, and simulate before signing. Never sign blindly—your hardware wallet display is the source of truth." +description: "Transaction verification guide: verify origin, smart contract address, function parameters, and simulate before signing. This section provides a guide" tags: - Engineer/Developer - Security Specialist @@ -10,10 +10,10 @@ contributors: users: [pinalikefruit, isaac, geoffrey, louis, pablo, dickson] - role: reviewed users: [Coinspect, engn33r] - + - role: fact-checked + users: [] --- - import { TagList, AttributionList, ContributeFooter } from '../../../../components' # Signing & Verification @@ -21,6 +21,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../../componen +> 🔑 **Key Takeaway**: Never sign blindly. Prefer the hardware wallet screen and independently verified calldata as +> ground truth over any web UI claim. + This section provides a guide to transaction verification, from basic EOA interactions to advanced multisig operations. The rule is to **never sign blindly**. Always take the time to verify what your wallet is asking you to approve. A @@ -66,6 +69,14 @@ act as smart contracts, with specific guidance for both users and developers. To apply these principles, this framework provides a curated list of verification and simulation tools in the **[Tools & Resources](/wallet-security/tools-and-resources)**. +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Smart Contract Interaction Security](/wallet-security/smart-contract-interaction-security): approvals, slippage, and + contract checks around signing +- [Tools & Resources](/wallet-security/tools-and-resources): simulation and calldata decoding tools for these checks +- [Wise Signer](https://wise-signer.cyfrin.io/): practice verifying real transactions before it counts + --- diff --git a/docs/pages/wallet-security/signing-and-verification/verifying-7702.mdx b/docs/pages/wallet-security/signing-and-verification/verifying-7702.mdx index ee919f2ab..b66a02aab 100644 --- a/docs/pages/wallet-security/signing-and-verification/verifying-7702.mdx +++ b/docs/pages/wallet-security/signing-and-verification/verifying-7702.mdx @@ -1,6 +1,6 @@ --- title: "Verifying EIP-7702 Transactions | SEAL" -description: "EIP-7702 security: enable smart contract features for EOAs including transaction batching and gas sponsorship. Protect against phishing attacks and multi-chain replay vulnerabilities." +description: "EIP-7702 security: enable smart contract features for EOAs including transaction batching and gas sponsorship. Protect against phishing attacks and multi-chain" tags: - Engineer/Developer - Security Specialist @@ -9,6 +9,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../../components' @@ -18,6 +20,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../../componen +> 🔑 **Key Takeaway**: EIP-7702 lets EOAs opt into smart-account behavior. Verify authorization scope carefully—new +> power means new ways to hand control to the wrong code. + The Pectra network upgrade introduces **EIP-7702**, which allows a standard Externally Owned Account (EOA) to temporarily function like a smart contract wallet. This is achieved via a new transaction type (`0x04`) that lets an EOA delegate its authority to a smart contract's code for the duration of a transaction or until it's changed. @@ -60,6 +65,15 @@ comes from an external link or pop-up. > ⚠️ Wallets will only prompt you to switch to a smart account within the wallet's native. Any request to do so via > email, a website, or a direct message is a phishing scam. +## Further Reading + +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the verification discipline + this builds on +- [Verifying Standard Transactions](/wallet-security/signing-and-verification/verifying-standard-transactions): the + baseline EOA checks +- [Account Abstraction Wallets](/wallet-security/account-abstraction): the smart account model 7702 borrows from +- [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702): the specification and its authorization semantics + --- diff --git a/docs/pages/wallet-security/signing-and-verification/verifying-standard-transactions.mdx b/docs/pages/wallet-security/signing-and-verification/verifying-standard-transactions.mdx index 69d229586..6d0ae38bd 100644 --- a/docs/pages/wallet-security/signing-and-verification/verifying-standard-transactions.mdx +++ b/docs/pages/wallet-security/signing-and-verification/verifying-standard-transactions.mdx @@ -1,6 +1,6 @@ --- title: "Verifying Standard Transactions | SEAL" -description: "Verify EOA transactions: check origin URL, smart contract address, function names, parameters, and gas fees. Cross-reference with official documentation and block explorers before signing." +description: "Verify EOA transactions: check origin URL, smart contract address, function names, parameters, and gas fees. Cross-reference with official documentation and" tags: - Engineer/Developer - Security Specialist @@ -9,6 +9,8 @@ contributors: users: [pinalikefruit] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../../components' @@ -18,6 +20,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../../componen +> 🔑 **Key Takeaway**: For EOA signing, verify recipient, amount, network, and calldata meaning—including token approvals—before +> confirming on the device. + When interacting with a dApp using a standard Externally Owned Account (EOA) via a wallet, you must verify several key components of the transaction request before signing. @@ -57,6 +62,15 @@ ensure the address is your own or the intended recipient. - **Why it's critical**: An unusually high gas fee for a simple operation can be a red flag, potentially indicating an inefficient or malicious contract designed to waste user funds. +## Further Reading + +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the principles behind these + four checks +- [Smart Contract Interaction Security](/wallet-security/smart-contract-interaction-security): what to check about the + contract itself +- [Using EIP-7702](/wallet-security/signing-and-verification/verifying-7702): extra checks once an EOA can delegate +- [Tools & Resources](/wallet-security/tools-and-resources): simulators and decoders for inspecting calldata + --- diff --git a/docs/pages/wallet-security/signing-schemes.mdx b/docs/pages/wallet-security/signing-schemes.mdx index 0f11d6e38..5750915df 100644 --- a/docs/pages/wallet-security/signing-schemes.mdx +++ b/docs/pages/wallet-security/signing-schemes.mdx @@ -1 +1,39 @@ +--- +title: "Signing Schemes | SEAL" +description: "Stub page for signing schemes under Wallet Security. Expand with practical custody and verification guidance. Placeholder page pending expert expansion of controls and..." +tags: + - Engineer/Developer + - Security Specialist +contributors: + - role: wrote + users: [] + - role: reviewed + users: [] + - role: fact-checked + users: [] +--- + +import { TagList, AttributionList, ContributeFooter } from '../../../components' + # Signing Schemes + + + + +> 🔑 **Key Takeaway**: This page is a placeholder until filled with dedicated guidance. + +Stub/in progress. Help contribute or expand this page. See the [Wallet Security overview](/wallet-security/overview) +and related cold/hot, seed phrase, and signing pages for production guidance. + +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): what signers should check + before approving +- [Secure Multisig Best Practices](/wallet-security/secure-multisig-best-practices): M-of-N schemes in operation +- [Account Abstraction Wallets](/wallet-security/account-abstraction): programmable validation beyond a single + keypair + +--- + + diff --git a/docs/pages/wallet-security/smart-contract-interaction-security.mdx b/docs/pages/wallet-security/smart-contract-interaction-security.mdx index 537e55119..e86fa6e69 100644 --- a/docs/pages/wallet-security/smart-contract-interaction-security.mdx +++ b/docs/pages/wallet-security/smart-contract-interaction-security.mdx @@ -1,6 +1,6 @@ --- title: "Smart Contract Interaction Security | SEAL" -description: "Secure smart contract interactions: manage approvals, understand permit risks, protect against MEV, and recognize common attack patterns like address poisoning and ice phishing." +description: "Secure smart contract interactions: manage approvals, understand permit risks, protect against MEV, and recognize common attack patterns like address poisoning and..." tags: - Engineer/Developer - Security Specialist @@ -124,6 +124,14 @@ in Microsoft threat research. - [ ] **Use MEV protection for DEX trades** — Route through Flashbots Protect or MEV Blocker. + +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the verification discipline + behind every interaction +- [Understanding Threat Vectors](/awareness/understanding-threat-vectors): drainers and approval exploits in context + --- diff --git a/docs/pages/wallet-security/software-wallets.mdx b/docs/pages/wallet-security/software-wallets.mdx index 68291b102..0bcf2c094 100644 --- a/docs/pages/wallet-security/software-wallets.mdx +++ b/docs/pages/wallet-security/software-wallets.mdx @@ -1 +1,37 @@ +--- +title: "Software Wallets | SEAL" +description: "Stub page for software wallets under Wallet Security. Expand with practical custody and verification guidance. Placeholder page pending expert expansion of controls an..." +tags: + - Engineer/Developer + - Security Specialist +contributors: + - role: wrote + users: [] + - role: reviewed + users: [] + - role: fact-checked + users: [] +--- + +import { TagList, AttributionList, ContributeFooter } from '../../../components' + # Software Wallets + + + + +> 🔑 **Key Takeaway**: This page is a placeholder until filled with dedicated guidance. + +Stub/in progress. Help contribute or expand this page. See the [Wallet Security overview](/wallet-security/overview) +and related cold/hot, seed phrase, and signing pages for production guidance. + +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Cold vs. Hot Wallets](/wallet-security/cold-vs-hot-wallet): where software wallets sit on the exposure scale +- [Tools & Resources](/wallet-security/tools-and-resources): reviewed wallet applications and selection criteria +- [Wallet Scrutiny](https://walletscrutiny.com/): independent reproducibility reviews of wallet apps + +--- + + diff --git a/docs/pages/wallet-security/tools-and-resources.mdx b/docs/pages/wallet-security/tools-and-resources.mdx index 61eca3c48..5792fc2d3 100644 --- a/docs/pages/wallet-security/tools-and-resources.mdx +++ b/docs/pages/wallet-security/tools-and-resources.mdx @@ -1,6 +1,6 @@ --- title: "Wallet Security Tools & Resources | SEAL" -description: "Wallet security tools: Wallet Scrutiny, Tenderly simulations, Safe transaction hash verification, calldata decoders, and interactive training platforms like Phishing Dojo and Wise Signer." +description: "Wallet security tools: Wallet Scrutiny, Tenderly simulations, Safe transaction hash verification, calldata decoders. This section provides a curated" tags: - Engineer/Developer - Security Specialist @@ -9,6 +9,8 @@ contributors: users: [pinalikefruit, auditware] - role: reviewed users: [Coinspect] + - role: fact-checked + users: [] --- import { TagList, AttributionList, ContributeFooter } from '../../../components' @@ -18,6 +20,9 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' +> 🔑 **Key Takeaway**: Independent wallet reviews, simulation, and calldata decoding tools only help when used before +> signing—not after a bad signature hardens on-chain. + This section provides a curated list of tools and resources to help users select wallets, practice safe signing habits, and verify transactions. Using these tools is a critical part of a robust security strategy. @@ -148,6 +153,14 @@ verification, and real-world hack analysis. - **[How to Multisig](https://howtomultisig.com/)**: A dedicated resource with best practices on how to implement secure standard operating procedures for multisig wallets. + +## Further Reading + +- [Wallet Security overview](/wallet-security/overview): how the pages of this framework fit together +- [Signing & Verification](/wallet-security/signing-and-verification/signing-verification): the workflow these tools + support +- [Monitoring Tools](/monitoring/tools): detection and alerting beyond wallet-level monitoring + --- diff --git a/vocs.config.ts b/vocs.config.ts index 3f3842ff4..b62de7e30 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -559,11 +559,14 @@ const config = { { text: 'Overview', link: '/wallet-security/overview' }, { text: 'Custodial vs Non-Custodial', link: '/wallet-security/custodial-vs-non-custodial' }, { text: 'Cold vs Hot Wallet', link: '/wallet-security/cold-vs-hot-wallet' }, + { text: 'Software Wallets', link: '/wallet-security/software-wallets', dev: true }, + { text: 'Hardware Wallets', link: '/wallet-security/hardware-wallets', dev: true }, { text: 'Wallets For Beginners & Small Balances', link: '/wallet-security/for-beginners-and-small-balances' }, { text: 'Wallets For Intermediates & Medium Funds', link: '/wallet-security/intermediates-and-medium-funds' }, { text: 'Multisig Wallets For Advanced Users & High Funds', link: '/wallet-security/secure-multisig-best-practices' }, { text: 'Account Abstraction Wallets', link: '/wallet-security/account-abstraction' }, { text: 'TEE-based Encumbered Wallets', link: '/wallet-security/encumbered-wallets' }, + { text: 'Signing Schemes', link: '/wallet-security/signing-schemes', dev: true }, { text: 'Signing & Verification', collapsed: false,