Skip to main content

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

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.

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
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);
  1. From mnemonic (BIP-39)
TypeScript
import { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';

const keypair = Ed25519Keypair.deriveKeypair(mnemonic, "m/44'/784'/0'/0'/0'");
  1. From Base64 String
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
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
  1. Verify with Ed25519
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.

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

const mnemonic = bip39.generateMnemonic(wordlist);