Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/axelarnetwork/axelar-core/llms.txt

Use this file to discover all available pages before exploring further.

The Multisig module implements distributed threshold cryptography for Axelar validators. It manages the full lifecycle of multi-party key generation (keygen) and signing sessions used to authorize gateway command batches on EVM chains. When a validator set needs to sign a new command batch or rotate the active gateway key, this module coordinates the distributed signing ceremony across all participating validators.

Key Generation

Runs distributed keygen sessions where validators collectively produce a shared key without any single party holding the full secret.

Signing Sessions

Aggregates individual validator signatures into threshold-valid multisig proofs that can be verified on EVM chains.

Key Rotation

Supports rotating the active key for any chain, allowing the validator set composition to change while maintaining gateway operatorship.

Opt-In / Opt-Out

Validators can opt into or out of specific keygen sessions, controlling their participation in chain-specific signing duties.

​
Key Concepts

​
KeyID

A KeyID is a unique string identifier for a generated key. It is assigned at the start of a keygen session and referenced throughout signing and rotation.

​
KeygenSession

A KeygenSession represents an active distributed key generation ceremony: 
func NewKeygenSession(
    id exported.KeyID,
    keygenThreshold utils.Threshold,
    signingThreshold utils.Threshold,
    snapshot snapshot.Snapshot,
    expiresAt int64,
    gracePeriod int64,
) KeygenSession {
    return KeygenSession{
        Key: Key{
            ID:               id,
            Snapshot:         snapshot,
            SigningThreshold: signingThreshold,
        },
        State:           exported.Pending,
        KeygenThreshold: keygenThreshold,
        ExpiresAt:       expiresAt,
        GracePeriod:     gracePeriod,
    }
}
The session is Pending until enough validators submit public keys, then transitions to Completed.

​
SigningSession

A SigningSession collects individual signature shares from validators for a specific payload hash: 
func NewSigningSession(
    id uint64,
    key Key,
    payloadHash exported.Hash,
    expiresAt int64,
    gracePeriod int64,
    module string,
    moduleMetadataProto ...codec.ProtoMarshaler,
) SigningSession
Once the SigningThreshold of validators have submitted their signatures, the session completes and the aggregated signature is available for broadcast.

​
Key

A Key holds the aggregated public key material produced by a completed keygen session, along with the snapshot of validators that participated and their signing threshold.

​
KeyEpoch

KeyEpoch tracks key rotation history — each chain can have multiple historical keys, and a new epoch is created each time rotate is called: 
func NewKeyEpoch(epoch uint64, chain nexus.ChainName, keyID exported.KeyID) KeyEpoch {
    return KeyEpoch{Epoch: epoch, Chain: chain, KeyID: keyID}
}

​
Keygen Lifecycle

1

Start Keygen

A governance-authorized account starts a new keygen session for a specific key ID. The current validator snapshot is taken as the participant set.
axelard tx multisig keygen start [key-id] \
  --from <gov-key> \
  --chain-id axelar-dojo-1
2

Opt-In / Opt-Out

Validators may opt in to participate in the keygen or opt out if they choose not to.
axelard tx multisig keygen opt-in [key-id] \
  --from <proxy-key>
axelard tx multisig keygen opt-out [key-id] \
  --from <proxy-key>
3

Submit Public Keys

Each participating validator’s vald process submits its public key contribution to the session.
4

Session Completes

Once the keygen threshold is reached, the session is marked completed and the new key is stored.

​
Signing Flow

When the EVM module calls sign-commands, the Multisig module creates a new signing session:
  1. A SigningSession is created with the current active key for the target chain.
  2. Each validator’s vald process observes the session and submits its signature share.
  3. Once the SigningThreshold of validators have signed, the session completes.
  4. The aggregated CommandBatch signature is stored and can be queried for submission to the gateway.
Signing sessions have a SigningTimeout (default 50 blocks = 10 × 5 for 1s block time) and a SigningGracePeriod (default 3 blocks) after expiry during which late submissions are still accepted.

​
Key Rotation

Rotate a chain to use a newly generated key. This also triggers a transferOperatorship command on the gateway: 
axelard tx multisig rotate ethereum [new-key-id] \
  --from <gov-key> \
  --chain-id axelar-dojo-1
After rotation, the old key epoch is archived and the new key becomes the active signing key for all subsequent sign-commands calls on that chain.

​
Module Parameters

​
KeygenThreshold
Threshold
required
Minimum fraction of validators that must submit public keys for a keygen session to complete. Default: 80/100.
​
SigningThreshold
Threshold
required
Minimum fraction of the keygen participants that must submit signatures for a signing session to complete. Default: 60/100.
​
KeygenTimeout
int64
required
Number of blocks before a keygen session expires. Default: 50 blocks (10 × 5 for 1s block time).
​
KeygenGracePeriod
int64
required
Number of blocks after KeygenTimeout during which late public key submissions are still accepted. Default: 3.
​
SigningTimeout
int64
required
Number of blocks before a signing session expires. Default: 50 blocks.
​
SigningGracePeriod
int64
required
Number of blocks after SigningTimeout during which late signatures are still accepted. Default: 3.
​
ActiveEpochCount
uint64
required
Number of past key epochs retained in active state. Older epochs are archived. Default: 5.
The KeygenTimeout and SigningTimeout defaults are 50 blocks (10 × 5 speed-up factor for 1-second block times). The KeygenGracePeriod and SigningGracePeriod defaults are 3 blocks each. These values were chosen to preserve approximately the same wall-clock duration as older, slower block times.

​
CLI Reference

​
Query Commands

# Get the key associated with a key ID
axelard query multisig key [key-id]

# Query the currently active key ID for a chain
axelard query multisig key-id ethereum

# Get the next key ID scheduled for rotation on a chain
axelard query multisig next-key-id ethereum

# Inspect a keygen session by key ID
axelard query multisig keygen-session [key-id]

# Show multisig module parameters
axelard query multisig params

​
Transaction Commands

# Start a new keygen session
axelard tx multisig keygen start [key-id] \
  --from <gov-key>

# Opt in to a keygen session
axelard tx multisig keygen opt-in [key-id] \
  --from <proxy-key>

# Opt out of a keygen session
axelard tx multisig keygen opt-out [key-id] \
  --from <proxy-key>

# Rotate a chain to a new key
axelard tx multisig rotate ethereum [new-key-id] \
  --from <gov-key>
Query axelard query multisig keygen-session [key-id] during an active ceremony to see how many validators have submitted public keys and whether the threshold has been reached.

Build docs developers (and LLMs) love

Get started for freeTalk to us