x/warden

Overview

The x/warden module is a module allowing users to create and manage their Spaces and request Keychains to sign payloads.

This module implements Warden's core concepts:

Usage

You can call the x/warden module from your EVM smart contract.

Concepts

Key

Keys in blockchain are paired to identify users and secure the ownership of wallets:

  • Public key: A public wallet address

  • Private key: A private code for signing transactions on the wallet

Keychain

A Keychain is a custodian that generates and stores keys and signs transactions, fulfilling key and signature requests from users.

Keychain software runs on Keychain operators' servers, and operators can optionally set a fee for each key/signature request.

Keychains are registered onchain. Each of them has the following:

  • A unique ID that identifies the Keychain in requests and collects fees

  • A list of admins that can update the Keychain information

  • A list of Keychain Writers—the only addresses authorized to publish signatures and keys

Analyzer

This is what Analyzers can do:

  • Extract payload metadata, which then can be referenced in expressions

  • Manipulate the payload before it's signed—for example, hash it following a specific algorithm

To illustrate this, it's possible to write an Ethereum Analyzer that will do the following:

  • Extract information: the value being sent and the destination address

  • Hash the payload using Ethereum's Keccak256 algorithm

State

The x/warden module keeps the state of the following primary objects:

  • Spaces

  • Keys

  • Keychains

  • Key requests

  • Signature requests

To manage this state, the module also keeps the following indexes:

  • Keys by Space ID

  • Spaces by owner address

Messages

MsgNewSpace

  • The Admin Rule

  • The Signing Rule

  • Additional owners

Note: If not specified, both the Admin and Signing Rules are set to the default Rule allowing any operation if at least 1 of the Space owners approves it.

This message is expected to fail in the following cases:

  • An owner is specified twice.

MsgNewKeychain

  • A human-readable description

  • A key request fee (optionally)

  • A signature request fee (optionally)

Note: The Keychain creator will be its first admin.

This message is expected to fail in the following cases:

  • The description is empty.

MsgUpdateKeychain

  • A human-readable description

  • A key request fee

  • A signature request fee

This message is expected to fail in the following cases:

  • The description is empty.

  • The creator isn't an admin of the Keychain.

MsgAddKeychainWriter

This message is expected to fail in the following cases:

  • The Writer is already a Writer of the Keychain.

  • The creator isn't an admin of the Keychain.

MsgFulfilKeyRequest

Updates a key request (KeyRequest) by ID:

  • On failure, submits a human-readable reason.

This message is expected to fail in the following cases:

  • The request isn't found

  • The status field doesn't match the contents of the result field.

MsgFulfilSignRequest

Updates a signature request (SignRequest) by ID:

  • On success, submits the signature bytes.

  • On failure, submits a human-readable reason.

This message is expected to fail in the following cases:

  • The request isn't found.

  • The status field doesn't match the content of the result field.

Actions

MsgAddSpaceOwner

The Rule applied: Space.AdminRule if present, the default Rule otherwise.

This message is expected to fail in the following cases:

  • The owner is already a member of the Space.

MsgRemoveSpaceOwner

The Rule applied: Space.AdminRule if present, the default Rule otherwise.

This message is expected to fail in the following cases:

  • The owner isn't a member of the Space.

MsgUpdateSpace

The Rule applied: Space.AdminRule if present, the default Rule otherwise.

This message is expected to fail in the following cases:

  • The specified Admin Rule ID doesn't exist.

  • The specified Signing Rule ID doesn't exist.

MsgUpdateKey

  • A new Rule for the Key

The Rule applied: Key.Rule if present, Space.SigningRule if present, the default Rule otherwise.

This message is expected to fail in the following cases:

  • The Key doesn't exist.

  • The Rule doesn't exist.

MsgNewSignRequest

The Rule applied: Key.Rule if present, Space.SigningRule if present, the default Rule otherwise.

This message is expected to fail in the following cases:

  • The Key doesn't exist.

  • One of the Analyzers doesn't exist.

  • One of the invoked Analyzers fails.

  • More than one Analyzer returns the data_for_signing field.

Events

Analyzers

Analyzers are CosmWasm smart contracts that implement the interface described below.

Input

An Analyze message is expected to be handled by the execute function of the Analyzer contract.

pub enum ExecuteMsg {
    Analyze { input: Binary },
}

Output

As a result, the Analyzer contract should return a Response where the data field is populated with a JSON-encoded AnalyzeResult:

pub struct AnalyzeResult<T> {
    pub data_for_signing: Option<Binary>,
    pub result: T,
}

In this code, T is another struct specific to the Analyzer, containing numeric or string fields.

Key request flow

Note: 1/3 of the voting power has to agree on the outcome of evaluation. Otherwise, the request is never broadcast to the Keychain. If an attacker wants to abuse the system, they need to obtain more than 1/3 of the voting power.

Note: Currently all Keychains available in Warden are MPC-based: each Keychain operator runs a network of MPC nodes. Potentially, a Keychain can be operated without an MPC network—Warden isn't in charge of it.

Diagram

This diagram represents the key request flow:

KeychainNode 2Node 1ClientKeychainNode 2Node 1Clientloop​Polling for new requestsloop​MsgNewKeyRequestKeyRequest 1234P2PQueryKeyRequestsKeyRequest 1234MsgFulfilKeyRequestP2PQueryKeysKey 1234

Signature request flow

Note: While key requests directly indicate the Keychain in the request, signature requests contain the Keychain ID inside the keys object.

2. Checking the Rule

  1. The transaction is included in a block and broadcast to the P2P network.

  2. All nodes in the network reach consensus on the validity of the transaction and re-evaluate the Approval Rule check.

Note: 1/3 of the voting power has to agree on the outcome of evaluation. Otherwise, the request is never broadcast to the Keychain. If an attacker wants to abuse the system, they need to obtain more than 1/3 of the voting power.

Diagram

This diagram represents the signature request flow:

Keychain

PreviousWarden Protocol modulesNextx/act

Last updated