From 8c39f41101b02e75425fe64f4d05acbf1f764fd9 Mon Sep 17 00:00:00 2001 From: xujikks Date: Mon, 14 Oct 2024 20:18:51 +0800 Subject: [PATCH] docs(crypto): update docs (#22247) Co-authored-by: keke-ka --- collections/quad.go | 4 ---- crypto/codec/pubkey.go | 16 ++++++++++++++ crypto/hd/hdpath.go | 10 ++++----- crypto/keyring/keyring.go | 44 +++++++++++++++++++++++++++++++++++++++ crypto/keyring/record.go | 7 +++++++ 5 files changed, 72 insertions(+), 9 deletions(-) diff --git a/collections/quad.go b/collections/quad.go index 2e0678e69ea2..9d8d42a60644 100644 --- a/collections/quad.go +++ b/collections/quad.go @@ -106,7 +106,6 @@ type quadKeyCodec[K1, K2, K3, K4 any] struct { type jsonQuadKey [4]json.RawMessage - // EncodeJSON encodes Quads to json func (t quadKeyCodec[K1, K2, K3, K4]) EncodeJSON(value Quad[K1, K2, K3, K4]) ([]byte, error) { json1, err := t.keyCodec1.EncodeJSON(*value.k1) @@ -210,7 +209,6 @@ func (t quadKeyCodec[K1, K2, K3, K4]) KeyType() string { return fmt.Sprintf("Quad[%s,%s,%s,%s]", t.keyCodec1.KeyType(), t.keyCodec2.KeyType(), t.keyCodec3.KeyType(), t.keyCodec4.KeyType()) } - func (t quadKeyCodec[K1, K2, K3, K4]) Encode(buffer []byte, key Quad[K1, K2, K3, K4]) (int, error) { writtenTotal := 0 if key.k1 != nil { @@ -243,8 +241,6 @@ func (t quadKeyCodec[K1, K2, K3, K4]) Encode(buffer []byte, key Quad[K1, K2, K3, } return writtenTotal, nil } - - func (t quadKeyCodec[K1, K2, K3, K4]) Decode(buffer []byte) (int, Quad[K1, K2, K3, K4], error) { readTotal := 0 read, key1, err := t.keyCodec1.DecodeNonTerminal(buffer) diff --git a/crypto/codec/pubkey.go b/crypto/codec/pubkey.go index c45f258517b0..7710e9275abc 100644 --- a/crypto/codec/pubkey.go +++ b/crypto/codec/pubkey.go @@ -11,6 +11,14 @@ import ( sdkerrors "github.com/cosmos/cosmos-sdk/types/errors" ) +// PubKeyToProto converts a JSON public key (in `cryptokeys.JSONPubkey` format) to its corresponding protobuf public key type. +// +// Parameters: +// - pk: A `cryptokeys.JSONPubkey` containing the public key and its type. +// +// Returns: +// - cryptotypes.PubKey: The protobuf public key corresponding to the provided JSON public key. +// - error: An error if the key type is invalid or unsupported. func PubKeyToProto(pk cryptokeys.JSONPubkey) (cryptotypes.PubKey, error) { switch pk.KeyType { case ed25519.PubKeyName: @@ -30,6 +38,14 @@ func PubKeyToProto(pk cryptokeys.JSONPubkey) (cryptotypes.PubKey, error) { } } +// PubKeyFromProto converts a protobuf public key (in `cryptotypes.PubKey` format) to a JSON public key format (`cryptokeys.JSONPubkey`). +// +// Parameters: +// - pk: A `cryptotypes.PubKey` which is the protobuf representation of a public key. +// +// Returns: +// - cryptokeys.JSONPubkey: The JSON-formatted public key corresponding to the provided protobuf public key. +// - error: An error if the key type is invalid or unsupported. func PubKeyFromProto(pk cryptotypes.PubKey) (cryptokeys.JSONPubkey, error) { switch pk := pk.(type) { case *ed25519.PubKey: diff --git a/crypto/hd/hdpath.go b/crypto/hd/hdpath.go index 9ef9961d1213..7e3107dfba77 100644 --- a/crypto/hd/hdpath.go +++ b/crypto/hd/hdpath.go @@ -230,11 +230,11 @@ func derivePrivateKey(privKeyBytes, chainCode [32]byte, index uint32, harden boo pubkeyBytes := ecPub.SerializeCompressed() data = pubkeyBytes - /* By using btcec, we can remove the dependency on tendermint/crypto/secp256k1 - pubkey := secp256k1.PrivKeySecp256k1(privKeyBytes).PubKey() - public := pubkey.(secp256k1.PubKeySecp256k1) - data = public[:] - */ + // By using btcec, we can remove the dependency on tendermint/crypto/secp256k1 + // pubkey := secp256k1.PrivKeySecp256k1(privKeyBytes).PubKey() + // public := pubkey.(secp256k1.PubKeySecp256k1) + // data = public[:] + } data = append(data, uint32ToBytes(index)...) diff --git a/crypto/keyring/keyring.go b/crypto/keyring/keyring.go index ef3b0a16df08..950ecbab440f 100644 --- a/crypto/keyring/keyring.go +++ b/crypto/keyring/keyring.go @@ -376,6 +376,17 @@ func (ks keystore) ImportPubKey(uid, armor string) error { return nil } +// Sign signs a message using the private key associated with the provided UID. +// +// Parameters: +// - uid: The unique identifier of the account/key to use for signing. +// - msg: The message or data to be signed. +// - signMode: The signing mode that specifies how the message should be signed. +// +// Returns: +// - []byte: The generated signature. +// - types.PubKey: The public key corresponding to the private key used for signing. +// - error: Any error encountered during the signing process. func (ks keystore) Sign(uid string, msg []byte, signMode signing.SignMode) ([]byte, types.PubKey, error) { k, err := ks.Key(uid) if err != nil { @@ -536,6 +547,19 @@ func (ks keystore) List() ([]*Record, error) { return ks.MigrateAll() } +// NewMnemonic generates a new mnemonic and derives a new account from it. +// +// Parameters: +// - uid: A unique identifier for the account. +// - language: The language for the mnemonic (only English is supported). +// - hdPath: The hierarchical deterministic (HD) path for key derivation. +// - bip39Passphrase: The passphrase used in conjunction with the mnemonic for BIP-39. +// - algo: The signature algorithm used for signing keys. +// +// Returns: +// - *Record: A new key record that contains the private and public key information. +// - string: The generated mnemonic phrase. +// - error: Any error encountered during the process. func (ks keystore) NewMnemonic(uid string, language Language, hdPath, bip39Passphrase string, algo SignatureAlgo) (*Record, string, error) { if language != English { return nil, "", ErrUnsupportedLanguage @@ -707,6 +731,15 @@ func newFileBackendKeyringConfig(name, dir string, buf io.Reader) keyring.Config } } +// newRealPrompt creates a password prompt function to retrieve or create a passphrase +// for the keyring system. +// +// Parameters: +// - dir: The directory where the keyhash file is stored. +// - buf: An io.Reader input, typically used for reading user input (e.g., the passphrase). +// +// Returns: +// - A function that accepts a prompt string and returns the passphrase or an error. func newRealPrompt(dir string, buf io.Reader) func(string) (string, error) { return func(prompt string) (string, error) { keyhashStored := false @@ -896,6 +929,7 @@ func (ks keystore) writeMultisigKey(name string, pk types.PubKey) (*Record, erro return k, ks.writeRecord(k) } +// MigrateAll migrates all legacy key information stored in the keystore to the new Record format. func (ks keystore) MigrateAll() ([]*Record, error) { keys, err := ks.db.Keys() if err != nil { @@ -1008,6 +1042,16 @@ func (ks keystore) SetItem(item keyring.Item) error { return ks.db.Set(item) } +// convertFromLegacyInfo converts a legacy account info (LegacyInfo) into a new Record format. +// It handles different types of legacy info and creates the corresponding Record based on the type. +// +// Parameters: +// - info: The legacy account information (LegacyInfo) that needs to be converted. +// It provides the name, public key, and other data depending on the type of account. + +// Returns: +// - *Record: A pointer to the newly created Record that corresponds to the legacy account info. +// - error: An error if the conversion fails due to invalid info or an unsupported account type. func (ks keystore) convertFromLegacyInfo(info LegacyInfo) (*Record, error) { if info == nil { return nil, errorsmod.Wrap(ErrLegacyToRecord, "info is nil") diff --git a/crypto/keyring/record.go b/crypto/keyring/record.go index 2e19c5b91576..009a89ebda35 100644 --- a/crypto/keyring/record.go +++ b/crypto/keyring/record.go @@ -128,6 +128,13 @@ func extractPrivKeyFromRecord(k *Record) (cryptotypes.PrivKey, error) { return extractPrivKeyFromLocal(rl) } +// extractPrivKeyFromLocal extracts the private key from a local record. +// It checks if the private key is available in the provided Record_Local instance. +// Parameters: +// - rl: A pointer to a Record_Local instance from which the private key will be extracted. +// Returns: +// - priv: The extracted cryptotypes.PrivKey if successful. +// - error: An error if the private key is not available or if the casting fails. func extractPrivKeyFromLocal(rl *Record_Local) (cryptotypes.PrivKey, error) { if rl.PrivKey == nil { return nil, ErrPrivKeyNotAvailable