Skip to main content

x/warden

Overview​

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

This module implements Warden's core concepts, which you can find in our Glossary:

Concepts​

Space​

A Space is a collection of users (owners) that share a common set of Rules:

  • Admin Rule: It's a applied to all admin operations such as adding or removing Space owners.
  • Signing Rule: It's applied to all signature operations such as requesting a new key or signature.
  • Default Rule: It's applied if no Rule is specified, allowing any operation if at least 1 of the Space owners approves it.

See also Glossary: Space.

Key​

A Key is the public part of a key pair, which is stored on-chain. Every Key belongs to a certain Space.

Keys have unique identifiers used to refer to them when requesting a Keychain to sign a payload.

See also Glossary: Key.

Keychain​

A Keychain fulfills key requests and signature requests from users. Optionally, it can set a fee for each request.

Keychains can be registered on-chain. Each Keychain has the following:

  • A list of admins that can update the Keychain information
  • A list of Writers – the only addresses authorized to send updates to requests

See also Glossary: Keychain, Request flow.

Analyzer​

An Analyzer is a CosmWasm contract that can intercept a payload before it's signed by a Keychain. Using Analyzers allows Keychains to receive the final payload without the need to have any knowledge of its content.

This is what Analyzers can do:

  • Extract payload metadata, which then can be referenced in Rule 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

You can learn more in the Analyzers section of this article.

State​

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

  • Spaces
  • Keys
  • Keychains
  • KeyRequests
  • SignRequests

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

  • Keys by Space ID
  • Spaces by owner address

Rules​

The x/warden module provides the following variables to be used in Rules:

  • warden.space.owners: The list of Space owners
  • warden.analyzers.<addr>.<name>: The Analyzer name and address

Messages​

MsgNewSpace​

Creates a new Space, optionally specifying the following:

  • 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​

Creates a new Keychain, specifying the following:

Note: The Keychain creator will be its first admin.

This message is expected to fail in the following cases:

  • The description is empty.

MsgUpdateKeychain​

Updates a Keychain by ID, specifying the following:

This message is expected to fail in the following cases:

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

MsgAddKeychainWriter​

Adds a new Writer to a Keychain.

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 success, submits the public key bytes.
  • On failure, submits a human-readable reason.

This message is expected to fail in the following cases:

  • The request isn't found.
  • The creator isn't a Writer of the Keychain.
  • The status field doesn't match the contents of the result field.

Learn more: Key request flow

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 creator isn't a Writer of the Keychain.
  • The status field doesn't match the content of the result field.

Learn more: Signature request flow

Actions​

The following messages must be wrapped inside Actions from the x/act module (instead of being executed directly by users).

MsgAddSpaceOwner​

Adds an owner to a Space.

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​

Removes an owner from a Space.

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​

Updates the Admin Rule and Signing Rule of a Space.

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.

MsgNewKeyRequest​

Creates a new key request (KeyRequest) for a given Keychain. The resulting Key will belong to a given Space. Optionally, the following can be specified:

  • A Rule that will be applied to the signing operations of the new Key

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

This message is expected to fail in the following cases:

  • The Space doesn't exist.
  • The Keychain doesn't exist.
  • The Rule doesn't exist.

Learn more: Key request flow

MsgUpdateKey​

Updates a Key by ID, specifying the following:

  • 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​

Creates a new signature request (SignRequest) for a given Key and the Keychain that created it. The following can be specified:

  • A list of Analyzer addresses. They will be invoked as part of this message to extract information from the payload.

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.

Learn more: Signature request flow

Events​

See the Protobuf definitions on GitHub.

Analyzers​

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

See a sample Analyzer on GitHub.

Input​

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

The input field of the message is the binary payload submitted by a user in MsgNewSignRequest.

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.

The data_for_signing field is the data that will be signed by the Keychain when the MsgNewSignRequest message is executed.

The fields of the result struct will be available for Rules to reference.