Skip to content

Latest commit

 

History

History
957 lines (727 loc) · 21.7 KB

README.md

File metadata and controls

957 lines (727 loc) · 21.7 KB
Raw

x/treasury

Abstract

This document specifies the treasury module of the Fusion Chain.

The treasury module's main purpose is the integration to keyrings by exposing ways of requesting keys and signatures to one respective keyring. Apart from requesting keys or signatures, owners can derive their keys into L1 wallets which get assigned to the respective workspace. Furthermore, the keyrings publish their responses in the treasury module.

Contents

Concepts

Key

Keys allow users to derive addresses and sign transactions or other arbitrary data. The treasury module exposes functions for workspace owners to request keys of various key types generated by a specified keyring. This allows a workspace and its owners to collectively control them and the L1 addresses that are being derived of them. Therefore, any key type that the keyring supports can be requested.

Wallet

A wallet describes an actual L1 address that got derived from a certain key. One key can be derived into different addresses per blockchain, for instance one for Ethereum and one for Cosmos Blockchains. Currently, the key type is defined as an enum on the Fusion Chain. In the future, we want to leave it to the keyring to define which key types it is supporting, effectively making Fusion Chain a keyring platform where keyrings can provide different services to their customers.

Signature

To prove ownership of a key and publish transactions a payload needs to be signed for each key. The treasury module offers ways of requesting signatures for a specific key generated by a specific keyring. The response gets published by the keyring to this module.

State

Keys

TBD

Wallets

TBD

Signatures

TBD

Msg Service

Msg/NewKeyRequest

A new key request can be created with the MsgNewKeyRequest.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L45C1-L50C2

The message has the transaction creator's address, the workspace address of the creator, the keyringId and the key type.

It's expected to fail if

  • creator is not correctly set (e.g. wrong address format, duplicates, or with 0 weight).
  • creator is not an owner of the workspace
  • keyringId is invalid
  • keytype is invalid

Msg/UpdateKeyRequest

Keyrings publish the response to a key request with MsgUpdateKeyRequest.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L56C1-L69C2

The message contains the creator's (keyring) address, the requestId, the status, and the result.

It's expected to fail if:

  • the creator is not correctly set (e.g. wrong address format, duplicates, or with 0 weight)
  • the requestId is invalid or already processed
  • the status is already fulfilled

Msg/NewWalletRequest

Workspace owners can derive a wallet from an existing key associated to their workspace with NewWalletRequest.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L99C1-L103C2

The message contains the creator's (owners) address, the walletType and the keyId to derive the wallet from. The Fusion Chain derives the address without interaction from the keyring.

It's expected to fail if:

  • the creator is not an owner of the workspace
  • the owner is not correctly set (e.g. wrong address format, duplicates, or with 0 weight)
  • the walletType is invalid
  • the KeyId does not exist inside the given workspace

Msg/NewSignatureRequest

The NewSignatureRequest can be used to request an signature for a key and an arbitrary payload.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L73C1-L77C2

Called by an owner of a workspace, the message specifies the creator of the transaction, the keyId to request the signature from and the payload.

It's expected to fail if:

  • the keyId is not part of a workspace where the creator is owner
  • they keyId is not valid

Msg/NewSignTransactionRequest

The NewSignTransactionRequest can be used to request an signature for a key and an unsigned transaction payload.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L107C1-L111C2

Called by an owner of a workspace, the message specifies the creator of the transaction, the walletId to request the signature from and the unsigned transaction as a payload. The unsigned transaction needs to be created by a client device outside of Fusion.

It's expected to fail if:

  • the unsigned transaction does not have the correct hash
  • creator is not an owner of the wallet's workspace
  • walletId is invalid

Msg/FulfilSignatureRequest

The FulfilSignatureRequest returns the signature to a signature request.

https://github.com/qredo/fusionchain/blob/962d2b28de5d3d5844b4774180cb9c24d7132b5c/blockchain/proto/fusionchain/treasury/tx.proto#L83C1-L95C2

The message contains the creator's (keyring) address, the requestId, the status, and the result.

  • the creator is not correctly set (e.g. wrong address format, duplicates, or with 0 weight)
  • the requestId is invalid or already processed
  • the status is already fulfilled

Client

CLI

A user can query and interact with the treasury module using the CLI.

Query

The query commands allow users to query treasury state.

fchain query treasury --help
Keys

The keys command allows users to query for existing keys on the Fusion Chain.

fchain query treasury keys [workspace_addr]

Example:

fchain query treasury keys qredoworkspace14a2hpadpsy9h5m6us54

Example Output:

- id: "1"
  keyring_id: "0"
  public_key: BAFP9NyDIRm8MvzzmX4OmsgFI0PdQawV1V55jCyqt4pQeIuKCoMcvxq55u0+NwzlT0bpvbEUrSU8L6fmYdmWiwk=
  type: KEY_TYPE_ECDSA_SECP256K1
  workspace_addr: qredoworkspace14a2hpadpsy9h5m6us54
pagination:
  next_key: null
  total: "1"
KeyRequest

The key-request command allows users to query for key-requests of a particular keyring.

fchain query treasury key-requests [keyring-id] [pending|fulfilled|rejected|all]

Example:

fchain query treasury key-requests 0 all

Example Output:

- creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
  id: "1"
  key_type: KEY_TYPE_ECDSA_SECP256K1
  keyring_id: "0"
  status: KEY_REQUEST_STATUS_FULFILLED
  success_key_id: "1"
  workspace_addr: qredoworkspace14a2hpadpsy9h5m6us54
pagination:
  next_key: null
  total: "1"
KeyRequestById

The key-request-by-id command allows users to query key request by its id.

fchain query treasury key-request-by-id [id]

Example:

fchain query treasury key-request-by-id 1

Example Output:

key_request:
  creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
  id: "1"
  key_type: KEY_TYPE_ECDSA_SECP256K1
  keyring_id: "0"
  status: KEY_REQUEST_STATUS_FULFILLED
  success_key_id: "1"
  workspace_addr: qredoworkspace14a2hpadpsy9h5m6us54
Wallets

The wallets command allows users to query wallets.

fchain query treasury wallets

Example:

fchain query treasury wallets

Example Output:

pagination:
  next_key: null
  total: "1"
wallets:
- address: 0xDd7bF79A2178ad544Fab0cfaB3f1c741fCb859d4
  wallet:
    id: "1"
    key_id: "1"
    type: WALLET_TYPE_ETH
WalletsById

The wallet-by-id command allows users to query wallets based on a given wallet id.

fchain query treasury wallet-by-id [id]

Example:

fchain query treasury wallet-by-id 1

Example Output:

wallet:
  address: 0xDd7bF79A2178ad544Fab0cfaB3f1c741fCb859d4
  wallet:
    id: "1"
    key_id: "1"
    type: WALLET_TYPE_ETH
SignatureRequests

The signature-requests command allows users to query a keyring's signature requests.

fchain query treasury signature-requests [keyring-id] [pending|fulfilled|rejected|all]

Example:

fchain query treasury signature-requests 0 all

Example Output:

pagination:
  next_key: null
  total: "1"
sign_requests:
- creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
  data_for_signing: B7+ijgC7k/ExVtJL27GLCUnwY9NXV79wCHCe9boUcrI=
  id: "1"
  key_id: "1"
  signed_data: ldQLNJ7QTJ5baInDmqcL3LLkZQDdxia1UiIys0rlJqo6Gv1PuZAKyTK3lI9ceGMA6SWmNgFMOtPjt+f+GXIb1QA=
  status: SIGN_REQUEST_STATUS_FULFILLED
SignatureRequestsById

The signature-requests-by-id command allows users to query a signature requests by its id.

fchain query treasury signature-request-by-id [id]

Example:

fchain query treasury signature-request-by-id 1

Example Output:

sign_request:
  creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
  data_for_signing: B7+ijgC7k/ExVtJL27GLCUnwY9NXV79wCHCe9boUcrI=
  id: "1"
  key_id: "1"
  signed_data: ldQLNJ7QTJ5baInDmqcL3LLkZQDdxia1UiIys0rlJqo6Gv1PuZAKyTK3lI9ceGMA6SWmNgFMOtPjt+f+GXIb1QA=
  status: SIGN_REQUEST_STATUS_FULFILLED
SignTransactionRequest

The sign-transaction-requests command allows users to query a transaction signature requests by its wallet_type.

fchain query treasury sign-transaction-requests [wallet_type]

Example:

fchain query treasury sign-transaction-requests ethereum

Example Output:

pagination:
  next_key: null
  total: "0"
sign_transaction_requests:
- sign_request:
    creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
    data_for_signing: WOp61tETjR5c2d4usgUbA5aoJCpKwmbjUwWNbgqyuV0=
    id: "2"
    key_id: "1"
    signed_data: BiBVLGHvCMSmXlW24JY9AnnKGljM/LaMOXAkQQCd1LkVuaQelctTTKMwcbirq7imz8lzUO4Emtv2tbLI6NdzbgE=
    status: SIGN_REQUEST_STATUS_FULFILLED
  sign_transaction_request:
    creator: qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j
    id: "1"
    sign_request_id: "2"
    unsigned_transaction: 64CFBKgXyACCUgiUmbln7x5s4CPlv4BOHI6um7JXJJeHDjX6kxoAAICAgIA=
    wallet_id: "1"

gRPC

Query

The query commands allow users to query treasury state.

Keys

The keys command allows users to query for existing keys on the Fusion Chain.

fusionchain.treasury.Query.Keys

Example:

grpcurl -plaintext -d '{"workspace_addr":"qredoworkspace14a2hpadpsy9h5m6us54"}' localhost:9090 fusionchain.treasury.Query.Keys

Example Output:

{
  "pagination": {
    "total": "1"
  },
  "keys": [
    {
      "id": "1",
      "workspaceAddr": "qredoworkspace14a2hpadpsy9h5m6us54",
      "type": "KEY_TYPE_ECDSA_SECP256K1",
      "publicKey": "BAFP9NyDIRm8MvzzmX4OmsgFI0PdQawV1V55jCyqt4pQeIuKCoMcvxq55u0+NwzlT0bpvbEUrSU8L6fmYdmWiwk="
    }
  ]
}
KeyRequest

The key-request command allows users to query for key-requests of a particular keyring.

fusionchain.treasury.Query.KeyRequests

Example:

grpcurl -plaintext -d '{"keyring_id":"0"}' localhost:9090 fusionchain.treasury.Query.KeyRequests

Example Output:

{
  "pagination": {
    "total": "2"
  },
  "keyRequests": [
    {
      "id": "1",
      "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "workspaceAddr": "qredoworkspace10j06zdk5gyl6vrss5d5",
      "keyType": "KEY_TYPE_ECDSA_SECP256K1",
      "status": "KEY_REQUEST_STATUS_FULFILLED",
      "successKeyId": "1"
    }
  ]
}
KeyRequestById

The key-request-by-id command allows users to query key request by its id.

fusionchain.treasury.Query.KeyRequestById

Example:

grpcurl -plaintext -d '{"id":"1"}' localhost:9090 fusionchain.treasury.Query.KeyRequestById

Example Output:

{
  "keyRequest": {
    "id": "1",
    "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
    "workspaceAddr": "qredoworkspace10j06zdk5gyl6vrss5d5",
    "keyType": "KEY_TYPE_ECDSA_SECP256K1",
    "status": "KEY_REQUEST_STATUS_FULFILLED",
    "successKeyId": "1"
  }
}
Wallets

The wallets command allows users to query wallets.

fusionchain.treasury.Query.Wallets

Example:

grpcurl -plaintext localhost:9090 fusionchain.treasury.Query.Wallets

Example Output:

{
  "pagination": {
    "total": "1"
  },
  "wallets": [
    {
      "wallet": {
        "id": "1",
        "type": "WALLET_TYPE_ETH",
        "keyId": "1"
      },
      "address": "0x28d7456ed05A574193BFE583aC2484a51B007e3B"
    }
  ]
}
WalletsById

The wallet-by-id command allows users to query wallets based on a given wallet id.

fusionchain.treasury.Query.WalletById

Example:

grpcurl -plaintext -d '{"id":"1"}' localhost:9090 fusionchain.treasury.Query.WalletById

Example Output:

{
  "wallet": {
    "wallet": {
      "id": "1",
      "type": "WALLET_TYPE_ETH",
      "keyId": "1"
    },
    "address": "0x28d7456ed05A574193BFE583aC2484a51B007e3B"
  }
}
SignatureRequests

The signature-requests command allows users to query a keyring's signature requests.

fusionchain.treasury.Query.SignatureRequests

Example:

grpcurl -plaintext -d '{"keyring_id":"0"}' localhost:9090 fusionchain.treasury.Query.SignatureRequests

Example Output:

{
  "pagination": {
    "total": "1"
  },
  "signRequests": [
    {
      "id": "1",
      "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "keyId": "1",
      "dataForSigning": "tSR4wa1srbASeiRWjzEKKC1PgSuPBuzuWosOEdj3NB0=",
      "status": "SIGN_REQUEST_STATUS_FULFILLED",
      "signedData": "Lnhyih8OH9e9IA0BkGIC+/ati2xKBoHia6Z9srNnhsQgFnlNJZyn7inUunUZ4lAIGIJ/wV1iBV7FmSzrGWsmXQA="
    }
  ]
}
SignatureRequestsById

The signature-requests-by-id command allows users to query a signature requests by its id.

fusionchain.treasury.Query.SignatureRequestById

Example:

grpcurl -plaintext -d '{"id":"1"}' localhost:9090 fusionchain.treasury.Query.SignatureRequestById

Example Output:

{
  "signRequest": {
    "id": "1",
    "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
    "keyId": "1",
    "dataForSigning": "tSR4wa1srbASeiRWjzEKKC1PgSuPBuzuWosOEdj3NB0=",
    "status": "SIGN_REQUEST_STATUS_FULFILLED",
    "signedData": "Lnhyih8OH9e9IA0BkGIC+/ati2xKBoHia6Z9srNnhsQgFnlNJZyn7inUunUZ4lAIGIJ/wV1iBV7FmSzrGWsmXQA="
  }
}
SignTransactionRequest

The sign-transaction-requests command allows users to query a transaction signature requests by its wallet_type.

fusionchain.treasury.Query.SignTransactionRequests

Example:

grpcurl -plaintext -d '{"wallet_type":"WALLET_TYPE_ETH"}' localhost:9090 fusionchain.treasury.Query.SignTransactionRequests

Example Output:

{
  "pagination": {
    "total": "1"
  },
  "signTransactionRequests": [
    {
      "signTransactionRequest": {
        "id": "1",
        "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
        "walletId": "1",
        "unsignedTransaction": "64CFBKgXyACCUgiUmbln7x5s4CPlv4BOHI6um7JXJJeHDjX6kxoAAICAgIA=",
        "signRequestId": "2"
      },
      "signRequest": {
        "id": "2",
        "creator": "qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
        "keyId": "1",
        "dataForSigning": "WOp61tETjR5c2d4usgUbA5aoJCpKwmbjUwWNbgqyuV0=",
        "status": "SIGN_REQUEST_STATUS_FULFILLED",
        "signedData": "fi1M8w7B9neMNU2BuVuf+577LOjQldPEThOwsArixyhKyMTp+hkpriLcJokQ9SRxqXyev7pyMuWWrotVlh2CuQA="
      }
    }
  ]
}

REST

A user can query the treasury module using REST endpoints.

Keys

The keys command allows users to query for existing keys on the Fusion Chain.

/fusionchain/treasury/keys

Example:

curl 'localhost:1317/fusionchain/treasury/keys?workspace_addr=qredoworkspace14a2hpadpsy9h5m6us54'

Example Output:

{
   "pagination":{
      "next_key":null,
      "total":"1"
   },
   "keys":[
      {
         "id":"2",
         "workspace_addr":"qredoworkspace14a2hpadpsy9h5m6us54",
         "keyring_id":"0",
         "type":"KEY_TYPE_ECDSA_SECP256K1",
         "public_key":"BH6SsgpggFj0r0ORDq0GAkOCWCS/NfiHtHCcTf5YDTA/0gZ3BYQsQJHeQGX6qTijUNt2npI59vI6aMh1JfeROYw="
      }
   ]
}
KeyRequest

The key-request command allows users to query for key-requests of a particular keyring.

/fusionchain/treasury/key_requests

Example:

curl 'localhost:1317/fusionchain/treasury/key_requests?keyring_id=0'

Example Output:

[
   {
      "id":"1",
      "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "workspace_addr":"qredoworkspace10j06zdk5gyl6vrss5d5",
      "keyring_id":"0",
      "key_type":"KEY_TYPE_ECDSA_SECP256K1",
      "status":"KEY_REQUEST_STATUS_FULFILLED",
      "success_key_id":"1"
   },
   {
      "id":"2",
      "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "workspace_addr":"qredoworkspace14a2hpadpsy9h5m6us54",
      "keyring_id":"0",
      "key_type":"KEY_TYPE_ECDSA_SECP256K1",
      "status":"KEY_REQUEST_STATUS_FULFILLED",
      "success_key_id":"2"
   }
]
KeyRequestById

The key-request-by-id command allows users to query key request by its id.

/fusionchain/treasury/key_request_by_id

Example:

curl 'localhost:1317/fusionchain/treasury/key_request_by_id?id=1'

Example Output:

{
   "key_request":{
      "id":"1",
      "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "workspace_addr":"qredoworkspace10j06zdk5gyl6vrss5d5",
      "keyring_id":"0",
      "key_type":"KEY_TYPE_ECDSA_SECP256K1",
      "status":"KEY_REQUEST_STATUS_FULFILLED",
      "success_key_id":"1"
   }
}
Wallets

The wallets command allows users to query wallets.

/fusionchain/treasury/wallets

Example:

curl 'localhost:1317/fusionchain/treasury/wallets'

Example Output:

{
   "pagination":{
      "next_key":null,
      "total":"1"
   },
   "wallets":[
      {
         "wallet":{
            "id":"1",
            "type":"WALLET_TYPE_ETH",
            "key_id":"1"
         },
         "address":"0x28d7456ed05A574193BFE583aC2484a51B007e3B"
      }
   ]
}
WalletsById

The wallet-by-id command allows users to query wallets based on a given wallet id.

/fusionchain/treasury/wallet_by_id'

Example:

curl 'localhost:1317/fusionchain/treasury/wallet_by_id?id=1'

Example Output:

{
   "wallet":{
      "wallet":{
         "id":"1",
         "type":"WALLET_TYPE_ETH",
         "key_id":"1"
      },
      "address":"0x28d7456ed05A574193BFE583aC2484a51B007e3B"
   }
}
SignatureRequests

The signature-requests command allows users to query a keyring's signature requests.

/fusionchain/treasury/get_signature_requests

Example:

curl 'localhost:1317/fusionchain/treasury/get_signature_requests?keyring_id=0'

Example Output:

{
   "pagination":{
      "next_key":null,
      "total":"1"
   },
   "sign_requests":[
      {
         "id":"1",
         "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
         "key_id":"1",
         "data_for_signing":"tSR4wa1srbASeiRWjzEKKC1PgSuPBuzuWosOEdj3NB0=",
         "status":"SIGN_REQUEST_STATUS_FULFILLED",
         "signed_data":"Lnhyih8OH9e9IA0BkGIC+/ati2xKBoHia6Z9srNnhsQgFnlNJZyn7inUunUZ4lAIGIJ/wV1iBV7FmSzrGWsmXQA="
      }
   ]
}
SignatureRequestsById

The signature-requests-by-id command allows users to query a signature requests by its id.

/fusionchain/treasury/signature_request_by_id

Example:

curl 'localhost:1317/fusionchain/treasury/signature_request_by_id?id=1'

Example Output:

{
   "sign_request":{
      "id":"1",
      "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
      "key_id":"1",
      "data_for_signing":"tSR4wa1srbASeiRWjzEKKC1PgSuPBuzuWosOEdj3NB0=",
      "status":"SIGN_REQUEST_STATUS_FULFILLED",
      "signed_data":"Lnhyih8OH9e9IA0BkGIC+/ati2xKBoHia6Z9srNnhsQgFnlNJZyn7inUunUZ4lAIGIJ/wV1iBV7FmSzrGWsmXQA="
   }
}
SignTransactionRequest

The sign-transaction-requests command allows users to query a transaction signature requests by its wallet_type.

/fusionchain/treasury/sign_transaction_requests

Example:

grpcurl -plaintext -d '{"wallet_type":"WALLET_TYPE_ETH"}' localhost:9090 fusionchain.treasury.Query.SignTransactionRequests
curl 'localhost:1317/fusionchain/treasury/sign_transaction_requests?wallettype=wallettypeeth'

Example Output:

{
   "pagination":{
      "next_key":null,
      "total":"1"
   },
   "sign_transaction_requests":[
      {
         "sign_transaction_request":{
            "id":"1",
            "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
            "wallet_id":"1",
            "unsigned_transaction":"64CFBKgXyACCUgiUmbln7x5s4CPlv4BOHI6um7JXJJeHDjX6kxoAAICAgIA=",
            "sign_request_id":"2"
         },
         "sign_request":{
            "id":"2",
            "creator":"qredo1d652c9nngq5cneak2whyaqa4g9ehr8psyl0t7j",
            "key_id":"1",
            "data_for_signing":"WOp61tETjR5c2d4usgUbA5aoJCpKwmbjUwWNbgqyuV0=",
            "status":"SIGN_REQUEST_STATUS_FULFILLED",
            "signed_data":"fi1M8w7B9neMNU2BuVuf+577LOjQldPEThOwsArixyhKyMTp+hkpriLcJokQ9SRxqXyev7pyMuWWrotVlh2CuQA="
         }
      }
   ]
}