Skip to main content
Version: 1.5

Key Lifecycle

Once we have already generated our key shares, we can refresh and also export them.
We show how to do this below.

Key Refresh​

Key Refresh (sometimes referred to as "Key Rotation") is a protocol that allows the devices to compute entirely new secret shares of the same public key.
Refreshing the key material frequently is considered a best practice for enhanced security, as it adds an element of time to the security setting.
Since even if one secret share was compromised, then after Key Refresh the compromised secret share will no longer be useful. Below is an example of how to use Key Refresh:

import com.sodot.kotlin_sdk.Ecdsa
import kotlinx.coroutines.runBlocking

// Assume we have N parties with T threshold
val N = 3
val T = 2
val API_KEY = "MY_API_KEY"
val HOST_URL = "demo.sodot.dev" // Your Relay URL

// A secret share was previously generated during keygen
val secretShare = "previously_stored_secret_share"

runBlocking {
    // Initialize the ECDSA scheme
    val ecdsa = Ecdsa(HOST_URL)

    // Your server creates a room for N parties
    val refreshRoomUuid = ecdsa.createRoom(HOST_URL, N, API_KEY)
    
    // All parties now join the refresh room using their current secret share
    val (pubkey, refreshedSecretShare) = ecdsa.refresh(
        refreshRoomUuid,
        secretShare
    )
    
    // Note: The public key remains the same
    // Store refreshedSecretShare securely for future use
    // It can now be used for signing under the same threshold, as well as be refreshed again
}

Key Reshare​

Key Resharing is a protocol that allows changing the threshold parameters of the distributed key. This can be useful when adding or removing participants, or when changing the threshold value.

There are two roles in the resharing process:

  • Remaining Parties: Participants who already have a secret share
  • New Parties: Participants who will receive a new secret share
import com.sodot.kotlin_sdk.Ecdsa
import kotlinx.coroutines.runBlocking

// Change from T=2 of N=3 to T'=3 of N'=5
val oldThreshold = 2
val newThreshold = 3
val API_KEY = "MY_API_KEY"
val HOST_URL = "demo.sodot.dev" // Your Relay URL

runBlocking {
    // Initialize the ECDSA scheme
    val ecdsa = Ecdsa(HOST_URL)

    // Your server creates a room for the resharing
    val reshareRoomUuid = ecdsa.createRoom(HOST_URL, 5, API_KEY)
    
    // For remaining parties (those who already have a secret share):
    val keygenIds = arrayOf("keygenId1", "keygenId2", "keygenId3", "keygenId4", "keygenId5")
    val secretShare = "previously_stored_secret_share"
    
    val (remainingPartyPubkey, remainingPartySecretShare) = ecdsa.reshareRemainingParty(
        reshareRoomUuid,
        newThreshold,
        secretShare,
        keygenIds
    )
    
    // For new parties:
    val keygenInitResult = ecdsa.initKeygen()
    
    val (newPartyPubkey, newPartySecretShare) = ecdsa.reshareNewParty(
        reshareRoomUuid,
        oldThreshold,
        newThreshold,
        keygenInitResult.keypair,
        keygenIds
    )
    
    // Both remaining and new parties should store their new secret shares
    // These can now be used with the new threshold parameters
}

Key Export​

In certain scenarios, you might need to export the full private key from the distributed key shares. This should be used with caution as it negates some of the security benefits of MPC.

import com.sodot.kotlin_sdk.Ecdsa
import kotlinx.coroutines.runBlocking

val API_KEY = "MY_API_KEY"
val HOST_URL = "demo.sodot.dev" // Your Relay URL
val secretShare = "previously_stored_secret_share"

runBlocking {
    // Initialize the ECDSA scheme
    val ecdsa = Ecdsa(HOST_URL)
    
    // First, get the export ID from the secret share
    val exportID = ecdsa.exportID(secretShare)
    
    // Create a room for the export process
    val exportRoomUuid = ecdsa.createRoom(HOST_URL, 2, API_KEY)
    
    // Export the full private key (requires threshold number of participants)
    val fullPrivateKey = ecdsa.exportFullPrivateKey(
        exportRoomUuid,
        secretShare,
        exportID
    )
    
    // Handle the full private key with extreme care
    // This key should be securely stored or used immediately and then discarded
}

// Alternatively, if you already have collected all secret shares offline:
val secretShares = arrayOf("share1", "share2") // At least threshold number of shares
val ecdsa = Ecdsa(HOST_URL)
val offlinePrivateKey = ecdsa.offlineExportFullPrivateKey(secretShares)

Key Import​

You can also import an existing private key into the MPC system to create distributed shares. This is useful for migrating existing keys to the MPC framework.

import com.sodot.kotlin_sdk.Ecdsa
import kotlinx.coroutines.runBlocking

val threshold = 2
val API_KEY = "MY_API_KEY"
val HOST_URL = "demo.sodot.dev" // Your Relay URL
val privateKey = byteArrayOf(/* your private key bytes */) // The private key to import

runBlocking {
    // Initialize the ECDSA scheme
    val ecdsa = Ecdsa(HOST_URL)

    // Create a room for the import process
    val importRoomUuid = ecdsa.createRoom(HOST_URL, 3, API_KEY)
    
    // All parties initialize key generation
    val keygenInitResult = ecdsa.initKeygen()
    
    // All parties exchange their keygenIds
    val keygenIds = arrayOf("keygenId1", "keygenId2", "keygenId3")
    
    // For the party importing the key (the importer):
    val (importerPubkey, importerSecretShare) = ecdsa.importPrivateKeyImporter(
        importRoomUuid,
        threshold,
        privateKey,
        keygenInitResult.keypair,
        keygenIds
    )
    
    // For all other parties (the recipients):
    val (recipientPubkey, recipientSecretShare) = ecdsa.importPrivateKeyRecipient(
        importRoomUuid,
        threshold,
        keygenInitResult.keypair,
        keygenIds
    )
    
    // All parties now have a secret share of the imported key
    // Store the secret share for future use
}