Keypairs and Wallets

Facts

Fact Sheet

• Sui keys, on disk for Sui binaries, are in file: $HOME/.sui/sui_config/sui.keystore
• Keys are persisted in the file as a JSON array
• Entries in the array are base64 encoded strings e.g.: AIUPxQveY18QxhDDdTO0D0OD6PNV+et50068d1g/rIyl
• The byte count of a base64 decoded string is 33
• The first byte of the decoded key indicates the key type followed by the 32 byte private key seed
• Key types:
  • 0 -> ed25519 keytype
  • 1 -> secp256k1 keytype
  • 2 -> secp256r1 keytype
• Public keys are generated from the private keys. The length of the public key in bytes:
  • ed25519 -> 32 bytes
  • secp256k1 -> 33 bytes
  • secp256r1 -> 33 bytes
• Sui addresses are hex strings 66 characters long with prefix '0x', e.g.: 0xa9e2db385f055cc0215a3cde268b76270535b9443807514f183be86926c219f4
• Sui addresses are generated by hashing the key type and the public key bytes, converting to a hex string
  and prefixing with '0x'
• blake2b is used for hashing

Suggested additions:

• How to verify a Keypair
• How to import/export (explain sui.keystore hexa need 'sui keytool convert' for wallet import).

How to get a list of keypairs and addresses

Sui CLI

sui keytool list

PySui

import base64
from pysui.sui.sui_config import SuiConfig

def key_look():
    """Show the addresses, public keys and keytypes from cofiguration."""
    cfg = SuiConfig.default_config()

    # Loop through configuration found keys (addresses are derived)
    for address, keypair in cfg.addresses_and_keys.items():
        # Convert the bytes from scheme_and_key to readable base64
        encoded_pubkey = base64.b64encode(keypair.public_key.scheme_and_key()).decode()
        # Print
        print(f"Address {address} public key {encoded_pubkey} keytype {keypair.scheme.name}")

How to generate a new Keypair

Different actions that you make with Sui libraries require a keypair. A keypair can be generated by using cryptographic algorithms such as: Ed25519, ECDSA Secp256k1 & ECDSA Secp256r1.

Sui CLI

# Create ED25519 keypair scheme
sui client new-address ed25519

# Create SECP256K1 keypair scheme
sui client new-address secp256k1

# Create SECP256R1 keypair scheme
sui client new-address secp256r1

Pysui

from pysui.abstracts.client_keypair import SignatureScheme
from pysui.sui.sui_config import SuiConfig

# The method we want to use is on the SuiConfig object
config = SuiConfig.default_config()

# Create a new ed25519 keypair and writes to sui.keystore
# With no additional arguments, pysui generates a 24 work mnemonic phrase and
# default derivation path associated with the key SignatureScheme

# ed25519
ed_mnemonics, ed_address = config.create_new_keypair_and_address(SignatureScheme.ED25519)
print(f"ed25519 Address: {ed_address.address} phrase: {ed_mnemonics}")

# secp256k1
k1_mnemonics, k1_address = config.create_new_keypair_and_address(SignatureScheme.SECP256K1)
print(f"secp256k1 Address: {k1_address.address} phrase: {k1_mnemonics}")

# secp256r1
r1_mnemonics, r1_address = config.create_new_keypair_and_address(SignatureScheme.SECP256R1)
print(f"secp256r1 Address: {r1_address.address} phrase: {r1_mnemonics}")

TypeScript

import { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';
import { Secp256k1Keypair } from "@mysten/sui.js/keypairs/secp256k1";

// Generate Ed25519 keypair
const keypair_ed25519 = new Ed25519Keypair();

// Generate Secp256k1 keypair
const keypair_secp256k1 = new Secp256k1Keypair();

How to restore a Keypair from a secret

If you already have your secret, you can get your Keypair and you can use it to perform different actions.

1. From Bytes Array

Sui CLI

Not supported

Pysui

# pysui automatically loads all keypairs from 'sui.keystore'
# However you can get a keypair from the secret key bytes:

import base64
from pysui.sui.sui_crypto import SuiKeyPairED25519

_ED25519_SECRET_KEYBYTES = [
  0, 133, 15, 197, 11, 222, 99, 95, 16, 198, 16, 195, 117, 51, 180,
  15, 67, 131, 232, 243, 85, 249, 235, 121, 211, 78, 188, 119, 88,
  63, 172, 140, 165
  ]

kp_ed25519 = SuiKeyPairED25519.from_bytes(bytearray(_ED25519_SECRET_KEYBYTES))

TypeScript

import { Secp256k1Keypair } from "@mysten/sui.js/keypairs/secp256k1";

const SECP256K1_SECRET_KEY = [
  59, 148, 11, 85, 134, 130, 61, 253, 2, 174, 59, 70, 27, 180, 51, 107, 94, 203,
  174, 253, 102, 39, 170, 146, 46, 252, 4, 143, 236, 12, 136, 28,
];
const secretKey = new Uint8Array(SECP256K1_SECRET_KEY);

const keypair = Secp256k1Keypair.fromSecretKey(secretKey);

2. From mnemonic (BIP-39)

Sui CLI

To be done. Add your contribution here.

Python

To be done. Add your contribution here.

TypeScript

import { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';

const keypair = Ed25519Keypair.deriveKeypair(mnemonic, "m/44'/784'/0'/0'/0'");

3. From base64 string

Sui CLI

Not supported

Pysui

# pysui automatically loads all keypairs from 'sui.keystore'
# However you can get a keypair from a base64 keystring

from pysui.sui.sui_crypto import keypair_from_keystring

_ED25519_SECRET_KEYSTRING = "AIUPxQveY18QxhDDdTO0D0OD6PNV+et50068d1g/rIyl"

kp_ed25519 = keypair_from_keystring(_ED25519_SECRET_KEYSTRING)

TypeScript

import { fromB64 } from "@mysten/bcs";
import { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';

const ED25519_SECRET_KEY = "mdqVWeFekT7pqy5T49+tV12jO0m+ESW7ki4zSU9JiCg=";

const secretKey = fromB64(ED25519_SECRET_KEY);

const keypair = Ed25519Keypair.fromSecretKey(secretKey);

How to verify a Keypair

If you are given a keypair, you can verify whether or not the secret matches the given public key

1. Verify with Secp256k1

Sui CLI

To be done. Add your contribution here.

Pysui

To be done. Add your contribution here.

TypeScript

import { Secp256k1Keypair } from "@mysten/sui.js/keypairs/secp256k1";

const publicKey = "Ah0VIwfGtysO0EGLDnDNgOf1KVuNhvVyLT9SE/vSOU82";

const keypair = Secp256k1Keypair.fromSecretKey(
  new Uint8Array([
    59, 148, 11, 85, 134, 130, 61, 253, 2, 174, 59, 70, 27, 180, 51, 107, 94,
    203, 174, 253, 102, 39, 170, 146, 46, 252, 4, 143, 236, 12, 136, 28,
  ])
);

console.log(keypair.getPublicKey().toBase64() == publicKey);
// true

2. Verify with Ed25519

Sui CLI

To be done. Add your contribution here.

Pysui

To be done. Add your contribution here.

TypeScript

import { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';
import { fromB64 } from "@mysten/bcs";

const publicKey = "Gy9JCW4+Xb0Pz6nAwM2S2as7IVRLNNXdSmXZi4eLmSI=";

const keypair = Ed25519Keypair.fromSecretKey(
  fromB64("mdqVWeFekT7pqy5T49+tV12jO0m+ESW7ki4zSU9JiCg=")
);

console.log(keypair.getPublicKey().toBase64() == publicKey);
// true

How to generate a mnemonic phrase

If you're creating a wallet, you will need to generate a mnemonic phrase so that the user can save it as a backup.

Sui CLI

To be done. Add your contribution here.

Pysui

# When creating a new address/keypair, as noted above, mnemonics are
# autogenerated if not provided. Either way, create_new_keypair_and_address
# returns both the mnemonics used to generate the keypair seed  and the new address

TypeScript

import * as bip39 from "@scure/bip39";
import { wordlist } from "@scure/bip39/wordlists/english";

const mnemonic = bip39.generateMnemonic(wordlist);