Skip to main content

Signing and Sending Transactions

Transaction authentication on Sui involves three core concepts: cryptographic keys that you control, addresses that identify accounts onchain, and signatures that prove ownership. Sui implements these concepts using widely accepted wallet specifications and multiple signature schemes.

Keys and addresses​

Sui adheres to widely accepted wallet specifications in the cryptocurrency industry, including BIP-32 and its variation SLIP-0010, BIP-44, and BIP-39, to facilitate key management for users. Sui supports pure Ed25519, ECDSA Secp256k1, ECDSA Secp256r1, and multisig for signed transactions.

Key derivation schemes​

For managing wallets that support the Ed25519 (EdDSA) signing scheme, Sui follows SLIP-0010, which enforces wallets to always derive child private keys from parent private keys using the hardened key path.

Sui follows BIP-32 for managing wallets that support the ECDSA Secp256k1 and ECDSA Secp256r1 signing schemes.

BIP-32 defines the hierarchical deterministic wallet structure to logically associate a set of keys. Grouping keys in this manner reduces the overhead of keeping track of a large number of private keys. This method also allows custodians to issue distinct managed addresses for each user account under one source of control. Using BIP-32 decouples the private key derivation from the public key derivation, enabling the watch-only wallet use case, where a chain of public keys and its addresses can be derived, while the private key can be kept offline for signing.

Key derivation paths​

BIP-44 further defines the 5 levels of the derivation path with their exact meanings:

m/purpose′/cointype′/account′/change/addressindexm / purpose' / coin_type' / account' / change / address_index

In this structure, the slashes indicate levels in the hierarchy.

The purpose level distinguishes different signing schemes:

  • 44 for Ed25519

  • 54 for ECDSA Secp256k1

  • 74 for Secp256r1

BIP-49 and BIP-84, for example, are used to identify script types in Bitcoin. Sui chose 54 to indicate ECDSA Secp256k1 because there is no existing BIP under 54, avoiding confusion with any Bitcoin standard.

The coin_type value is managed with a repository of all other cryptocurrencies. Both signature schemes use Sui's registered coin_type: 784.

The account level is used for logically separating user accounts and creating specific account categories.

Account-based currencies define only the first 3 levels, while UTXO-based currencies add change and address level definitions. Because Sui's object-oriented data model is neither UTXO or account-based (it combines both), it employs all 5 levels for maximum compatibility.

SchemePathComments
Ed25519m/44'/784'/{account}'/{change}'/{address}'Each level of the derivation path is hardened.
ECDSA Secp256k1m/54'/784'/{account}'/{change}/{address}The first 3 levels are hardened.
ECDSA Secp256r1m/74'/784'/{account}'/{change}/{address}The first 3 levels are hardened.

Mnemonics support​

After Sui defines the deterministic way to derive the master key from a seed, BIP-39 is introduced to make the seed more human-readable and memorable using mnemonics. Sui accepts 12, 15, 18, 21, and 24 words from the BIP-39 word list that is properly checksummed, corresponding to 128, 160, 192, 224, and 256 bits of entropy.

Address format​

For deriving a 32-byte Sui address, Sui hashes the signature scheme flag 1-byte concatenated with public key bytes using the BLAKE2b (256 bits output) hashing function. Sui addresses currently support pure Ed25519, Secp256k1, Secp256r1, and multisig with corresponding flag bytes of 0x00, 0x01, 0x02, and 0x03, respectively.

Signatures​

When a user submits a signed transaction, a serialized signature and serialized transaction data is submitted. The serialized transaction data is the Binary Canonical Serialization serialized bytes of the struct TransactionData and the serialized signature is defined as a concatenation of bytes of flag || sig || pk.

Signature structure​

A Sui signature consists of three components concatenated together:

  • flag: A 1-byte representation corresponding to the signature scheme.

  • sig: The compressed bytes representation of the signature (not DER encoding).

  • pk: The bytes representation of the public key corresponding to the signature.

Supported signature schemes​

The following table lists each signing scheme and its corresponding flag, signature format, and public key format:

SchemeFlagSignature FormatPublic Key Format
Pure Ed255190x00Compressed, 64 bytesCompressed, 32 bytes
ECDSA Secp256k10x01Non-recoverable, compressed, 64 bytesCompressed, 33 bytes
ECDSA Secp256r10x02Non-recoverable, compressed, 64 bytesCompressed, 33 bytes
multisig0x03BCS serialized all signatures, size variesBCS serialized all participating public keys, size varies
zkLogin0x05BCS serialized zkLogin inputs, max epoch and ephemeral signature, size variesConcatenation of iss length, iss bytes, address seed padded to 32-bytes, size varies
passkey0x06BCS serialized passkey inputs (authenticatorData, clientDataJson, userSignature), size variesCompressed, 33 bytes

Signature requirements​

The signature must commit to the hash of the intent message of the transaction data, which you can construct by appending the 3-byte intent before the BCS serialized transaction data. To learn more on what an intent is and how to construct an intent message, see Intent Signing.

When invoking the signing API, you must first hash the intent message of the transaction data to 32 bytes using Blake2b. This external hashing is distinct from the hashing performed inside the signing API. To be compatible with existing standards and hardware secure modules (HSMs), the signing algorithms perform additional hashing internally. For ECDSA Secp256k1 and Secp256r1, you must use SHA-2 SHA256 as the internal hash function. For pure Ed25519, you must use SHA-512.

ECDSA signature requirements​

An accepted ECDSA Secp256k1 and Secp256r1 signature must follow:

  1. The internal hash used by ECDSA must be SHA256 SHA-2 hash of the transaction data. Sui uses SHA256 because it is supported by Apple, HSMs, and it is widely adopted by Bitcoin.

  2. The signature must be of length 64 bytes in the form of [r, s] where the first 32 bytes are r, the second 32 bytes are s.

  3. The r value can be between 0x1 and 0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364140 (inclusive).

  4. The s value must be in the lower half of the curve order. If the signature is too high, convert it to a lower s according to BIP-0062 with the corresponding curve orders using order - s. For Secp256k1, the curve order is 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141. For Secp256r1, the curve order is 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551 defined in Standards for Efficient Cryptography.

  5. Ideally, the signature must be generated with deterministic nonce according to RFC6979.

Ed25519 signature requirements​

An accepted pure Ed25519 signature must follow:

  1. The signature must be produced according to RFC 8032. The internal hash used is SHA-512.

  2. The signature must be valid according to ZIP215.

Special signature schemes​

For more information on advanced signature schemes:

  • zkLogin: See zkLogin for details on zero-knowledge login signatures.

  • Passkey: See SIP-8 for passkey implementation details.

  • Multisig: See Multisig for multi-signature transactions.

  • Offline Signing: See Offline Signing for concrete examples of signing transactions offline.

Authority signatures​

Sui's collection of validators holds 3 distinctive key pairs for different purposes.

Protocol key pair​

The protocol key pair provides authority signatures on user-signed transactions if they are verified. When a stake of the authorities that provide signatures on user transactions passes the required 2/3 threshold, Sui executes the transaction. Sui uses the BLS12381 scheme for its fast verification on aggregated signatures for a given number of authorities. In particular, Sui uses the minSig BLS mode, where each individual public key is 96 bytes, while the signature is 48 bytes. The latter is important as typically validators register their keys once at the beginning of each epoch and then they continuously sign transactions; thus, Sui optimizes on minimum signature size.

As with the BLS scheme, you can aggregate independent signatures resulting in a single BLS signature payload. Sui also accompanies the aggregated signature with a bitmap to denote which of the validators signed. This effectively reduces the authorities signature size from (2f + 1) × BLS_sig size to just 1 BLS_sig payload. This has significant network cost benefits resulting in compressed transaction certificates independently on the validators set size.

To counter potential rogue key attacks on BLS12381 aggregated signatures, proof of knowledge of the secret key (KOSK) is used during authority registration. When an authority requests to be added to the validator set, a proof of possession is submitted and verified. See Intent Signing on how to create a proof of possession. Unlike most standards, the Sui proof of knowledge scheme commits to the address as well, which offers an extra protection against adversarial reuse of a validator BLS key from another malicious validator.

Account key pair​

The account that the authority uses to receive payments on staking rewards is secured by the account key pair. Sui uses pure Ed25519 as the signing scheme.

Network key pair​

The private key is used to perform the TLS handshake required for consensus networking. The public key is used for validator identity. Pure Ed25519 is used as the scheme.

See more authority key toolings in Validator Tool.

Examples​

The Sui CLI tool and the Sui SDKs provide a flexible interface to sign transactions with various signing schemes.

$ sui keytool import "TEST_MNEMONIC" ed25519 "m/44'/784'/0'/0'/0'"
$ sui client new-address ed25519 "m/44'/784'/0'/0'/0'"

See more test vectors for pure Ed25519 or ECDSA Secp256k1.

Workflow​

The following high-level process describes the overall workflow for constructing, signing, and executing an onchain transaction:

  1. Construct the transaction data by creating a Transaction where multiple commands are chained. See Building Programmable Transaction Blocks for more information.

  2. The SDK's built-in gas estimation and coin selection picks the gas coin.

  3. Sign the transaction to generate a signature.

  4. Submit the Transaction and its signature for onchain execution.

info

If you are using the address balances feature, the feature automatically removes the need to select or merge gas coins entirely.

If you want to use a specific gas coin, first find the gas coin object ID to be used to pay for gas and explicitly use that in the PTB. If there is no gas coin object, use the splitCoin transaction to create a gas coin object. The split coin transaction should be the first transaction call in the PTB.

Process multiple transactions from the same address​

The Sui SDK offers transaction executors to help process multiple transactions from the same address.

SerialTransactionExecutor​

Use the SerialTransactionExecutor when you process transactions one after another. The executor grabs all the coins from the sender and combines them into a single coin that is used for all transactions.

Using the SerialTransactionExecutor prevents SequenceNumber errors by handling the versioning of object inputs across a PTB.

ParallelTransactionExecutor​

Use the ParallelTransactionExecutor when you want to process transactions with the same sender at the same time. This class creates a pool of gas coins that it manages to ensure parallel transactions don't equivocate those coins. The class tracks objects used across transactions and orders their processing so that the object inputs are also not equivocated.

Examples of signing transactions​

The following examples demonstrate how to sign and execute transactions using Rust, TypeScript, or the Sui CLI.

There are various ways to instantiate a key pair and to derive its public key and Sui address using the Sui TypeScript SDK.

import { fromHex } from '@mysten/bcs';
import { type Keypair } from '@mysten/sui/cryptography';
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { Secp256k1Keypair } from '@mysten/sui/keypairs/secp256k1';
import { Secp256r1Keypair } from '@mysten/sui/keypairs/secp256r1';
import { Transaction } from '@mysten/sui/transactions';

const kp_rand_0 = new Ed25519Keypair();
const kp_rand_1 = new Secp256k1Keypair();
const kp_rand_2 = new Secp256r1Keypair();

const kp_import_0 = Ed25519Keypair.fromSecretKey(
	fromHex('0xd463e11c7915945e86ac2b72d88b8190cfad8ff7b48e7eb892c275a5cf0a3e82'),
);
const kp_import_1 = Secp256k1Keypair.fromSecretKey(
	fromHex('0xd463e11c7915945e86ac2b72d88b8190cfad8ff7b48e7eb892c275a5cf0a3e82'),
);
const kp_import_2 = Secp256r1Keypair.fromSecretKey(
	fromHex('0xd463e11c7915945e86ac2b72d88b8190cfad8ff7b48e7eb892c275a5cf0a3e82'),
);

// $MNEMONICS refers to 12/15/18/21/24 words from the wordlist, for example, "retire skin goose will hurry this field stadium drastic label husband venture cruel toe wire". Refer to [Keys and Addresses](/develop/transactions/transaction-auth/auth-overview) for more.
const kp_derive_0 = Ed25519Keypair.deriveKeypair('$MNEMONICS');
const kp_derive_1 = Secp256k1Keypair.deriveKeypair('$MNEMONICS');
const kp_derive_2 = Secp256r1Keypair.deriveKeypair('$MNEMONICS');

const kp_derive_with_path_0 = Ed25519Keypair.deriveKeypair('$MNEMONICS', "m/44'/784'/1'/0'/0'");
const kp_derive_with_path_1 = Secp256k1Keypair.deriveKeypair('$MNEMONICS', "m/54'/784'/1'/0/0");
const kp_derive_with_path_2 = Secp256r1Keypair.deriveKeypair('$MNEMONICS', "m/74'/784'/1'/0/0");

// replace `kp_rand_0` with the variable names above.
const pk = kp_rand_0.getPublicKey();
const sender = pk.toSuiAddress();

// create an example transaction.
const txb = new Transaction();
txb.setSender(sender);
txb.setGasPrice(5);
txb.setGasBudget(100);
const bytes = await txb.build();
const serializedSignature = (await keypair.signTransaction(bytes)).signature;

// verify the signature locally
expect(await keypair.getPublicKey().verifyTransaction(bytes, serializedSignature)).toEqual(true);

// define sui client for the desired network.
const client = new SuiGrpcClient({
	baseUrl: 'https://fullnode.testnet.sui.io:443',
	network: 'testnet',
});

// execute transaction.
let res = await client.executeTransaction({
	transaction: bytes,
	signatures: [serializedSignature],
});
console.log(res);