forked from cosmos/cosmos-sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into feat/cosmos#20219
- Loading branch information
Showing
23 changed files
with
300 additions
and
49 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
# Crypto | ||
|
||
The `crypto` directory contains the components responsible for handling cryptographic operations, key management, and secure interactions with hardware wallets. | ||
|
||
## Components | ||
|
||
### Keyring | ||
|
||
Keyring is the primary interface for managing cryptographic keys. It provides a unified API to create, store, retrieve, and manage keys securely across different storage backends. | ||
|
||
#### Supported Backends | ||
|
||
* **OS**: Uses the operating system's default credential store. | ||
* **File**: Stores encrypted keyring in the application's configuration directory. | ||
* **KWallet**: Integrates with KDE Wallet Manager. | ||
* **Pass**: Leverages the `pass` command-line utility. | ||
* **Keyctl**: Uses Linux's kernel security key management system. | ||
* **Test**: Stores (insecurely) keys to disk for testing purposes. | ||
* **Memory**: Provides transient storage where keys are discarded when the process terminates. | ||
|
||
### Codec | ||
|
||
The Codec component handles serialization and deserialization of cryptographic structures in the crypto package. It ensures proper encoding of keys, signatures, and other artifacts for storage and transmission. The Codec also manages conversion between CometBFT and SDK key formats. | ||
|
||
### Ledger Integration | ||
|
||
Support for Ledger hardware wallets is integrated to provide enhanced security for key management and signing operations. The Ledger integration supports SECP256K1 keys and offers various features: | ||
|
||
#### Key Features | ||
|
||
* **Public Key Retrieval**: Supports both safe (with user verification) and unsafe (without user verification) methods to retrieve public keys from the Ledger device. | ||
* **Address Generation**: Can generate and display Bech32 addresses on the Ledger device for user verification. | ||
* **Transaction Signing**: Allows signing of transactions with user confirmation on the Ledger device. | ||
* **Multiple HD Path Support**: Supports various BIP44 derivation paths for key generation and management. | ||
* **Customizable Options**: Provides options to customize Ledger usage, including app name, public key creation, and DER to BER signature conversion. | ||
|
||
#### Implementation Details | ||
|
||
* The integration is built to work with or without CGO. | ||
* It includes a mock implementation for testing purposes, which can be enabled with the `test_ledger_mock` build tag. | ||
* The real Ledger device interaction is implemented when the `ledger` build tag is used. | ||
* The integration supports both SIGN_MODE_LEGACY_AMINO_JSON and SIGN_MODE_TEXTUAL signing modes. | ||
|
||
#### Usage Considerations | ||
|
||
* Ledger support requires the appropriate Cosmos app to be installed and opened on the Ledger device. | ||
* The integration includes safeguards to prevent key overwriting and ensures that the correct device and app are being used. | ||
|
||
#### Security Notes | ||
|
||
* The integration includes methods to validate keys and addresses with user confirmation on the Ledger device. | ||
* It's recommended to use the safe methods that require user verification for critical operations like key generation and address display. | ||
* The mock implementation should only be used for testing and development purposes, not in production environments. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,111 @@ | ||
# Migration Manager | ||
|
||
The `migration` package contains the `migration.Manager`, which is responsible | ||
for migrating data from `store/v1` to `store/v2`. To ensure a smooth transition, | ||
the process is designed to **lazily** migrate data in the background without blocking | ||
`root.Store` operations. | ||
|
||
## Overview | ||
|
||
The migration process involves several steps: | ||
|
||
1. **Create a snapshot** of the current state while `Commit` operations continue to | ||
function with `store/v1`. | ||
2. **Restore the snapshot** into the new StateStorage (SS) and StateCommitment (SC). | ||
3. **Sync recent state changes** from `store/v1` to the new SS and SC. | ||
4. After syncing, the `Commit` operation will be switched to the new `store/v2`. | ||
|
||
Taking a snapshot is a lightweight operation. The snapshot is not stored on disk but | ||
consumed by the `Restore` process, which replays state changes to the new SS and SC. | ||
|
||
> **Note:** After migration, `store/v2` does **not** support historical queries. | ||
If historical data access is required, a full state migration to `store/v2` is necessary. | ||
|
||
## Usage | ||
|
||
You can create a new `migration.Manager` by calling the following function: | ||
|
||
```go | ||
func NewManager( | ||
db corestore.KVStoreWithBatch, | ||
sm *snapshots.Manager, | ||
ss *storage.StorageStore, | ||
sc *commitment.CommitStore, | ||
logger log.Logger | ||
) *Manager | ||
``` | ||
|
||
* `sc` (Commitment Store) can be `nil`. In that case, the Manager will migrate only | ||
the state storage. | ||
* The migration process is lazy, meaning data is migrated in the background while | ||
`root.Store` remains fully operational. | ||
|
||
To initiate the migration process, call the `Start` method: | ||
|
||
```go | ||
func (m *Manager) Start(ctx context.Context) error | ||
``` | ||
|
||
> **Note:** It should be called by the RootStore, running in the background. | ||
|
||
## Migration Flow | ||
|
||
```mermaid | ||
sequenceDiagram | ||
autonumber | ||
|
||
participant A as RootStore | ||
participant B as MigrationManager | ||
participant C as SnapshotsManager | ||
participant D as StateCommitment | ||
participant E as StateStorage | ||
|
||
A->>B: Start | ||
loop Old Data Migration | ||
B->>C: Create Snapshot | ||
C->>B: Stream Snapshot | ||
B->>D: State Sync (Restore) | ||
B->>E: Write Changeset (Restore) | ||
end | ||
|
||
loop New Commit Data Sync | ||
A->>B: Commit(Changeset) | ||
B->>B: Store Changeset | ||
B->>D: Commit Changeset | ||
B->>E: Write Changeset | ||
end | ||
|
||
B->>A: Switch to new store/v2 | ||
``` | ||
|
||
## Key Considerations | ||
|
||
### Laziness and Background Operation | ||
|
||
The migration is performed lazily, meaning it occurs in the background without | ||
interrupting the current operations on root.Store. This allows the chain to continue | ||
running while data is gradually migrated to `store/v2`. State synchronization ensures | ||
that any new state changes during the migration are also applied to `store/v2`. | ||
|
||
However, note that there may be a performance impact depending on the size of the data | ||
being migrated, and it’s essential to monitor the migration process in production | ||
environments. | ||
|
||
### Handling Failures and Rollbacks | ||
|
||
It is important to consider how the migration manager handles errors or system failures | ||
during the migration process: | ||
|
||
* If the migration fails, there is no impact on the existing `store/v1` operations, | ||
but need to restart the migration process from the scratch. | ||
* In the event of a critical failure after migration, a rollback may not be possible, | ||
and it is needed to keep the `store/v1` backup for a certain period. | ||
|
||
### Impact on Historical Queries | ||
|
||
After the migration, the new `store/v2` does not support historical queries. | ||
This limitation should be clearly understood before starting the migration process, | ||
especially if the node relies on historical data for any operations. | ||
|
||
If historical queries are required, users must fully migrate all historical data to `store/v2`. | ||
Alternatively, keeping store/v1 accessible for historical queries could be an option. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.