Skip to main content

Fulfill requests from CLI

Overview​

This is a step-by-step guide explaining how to fulfill key and signature requests with your Keychain from the command line.

You'll interact with the node through node commands. For generating keys and signing messages, you'll use CLIChain – a command-line tool for managing cryptographic keys and operations.

You can either run a local chain to test your configuration or interact with Chiado testnet. In the provided code snippets, you'll find tabs with different versions of node commands.

Learn more:

Prerequisites​

If you wish to operate a Keychain locally, complete the following prerequisites:

To operate a Keychain on Chiado, complete these prerequisites:

  • Create a Keychain. These steps involve creating an account (key) on Chiado.

  • Use your key to create a Space:

    wardend tx warden new-space \
      --from my-key-name \
      --fees 400000000award \
      --chain-id chiado_1001-1 \
      --node https://rpc.chiado.wardenprotocol.org:443

  • Query Spaces. The list will contain Space IDs and account addresses. You should note down the Space ID associated with your address.

    wardend query warden spaces \
    --node https://rpc.chiado.wardenprotocol.org:443

1. Install CLIChain​

To install CLIChain, navigate to the wardenprotocol directory and run this:

go install ./cmd/clichain

2. Export variables​

The next steps require that you export your node and Keychain settings as environment variables. If you used our just script to run the node, you can export the predefined settings. Otherwise, use custom values.

export CHAIN_ID=warden_1337-1 
export KEY_NAME=shulgin
export SPACE_ID=1
export KEYCHAIN_ID=1
export KEYCHAIN_WRITER_NAME=shulgin
  • CHAIN_ID: The chain ID you used when running a node.
    Returned by wardend status in the network field.
  • KEY_NAME: Your local account name, or key name.
    Returned by wardend keys list.
  • SPACE_ID: Your Space ID.
    Returned by wardend query warden spaces.
  • KEYCHAIN_ID: Your Keychain ID obtained when registering a Keychain.
    Returned by wardend query warden keychains in the id field.
  • KEYCHAIN_WRITER_NAME: Your Keychain Writer name specified when adding a Keychain Writer.
    Returned by wardend keys list.
  • RPC_URL: The RPC URL for interacting with Chiado.

3. Fulfill a key request​

When a user requests a new key, the Keychain generates a new private key, stores it securely, and submits the public key to the chain. To test this flow, take the steps below.

  1. Request a new key:

    wardend tx warden new-action new-key-request \
      --from $KEY_NAME \
      --space-id $SPACE_ID \
      --keychain-id $KEYCHAIN_ID \
      --key-type KEY_TYPE_ECDSA_SECP256K1 \
      -y \
      --chain-id $CHAIN_ID \
    | wardend query wait-tx

  2. Get all key requests:

    wardend query warden key-requests --keychain-id $KEYCHAIN_ID

    Your request ID will be returned in the id field of the output:

    key_requests:
    - creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5
      deducted_keychain_fees: []
      id: "1"
      key_type: KEY_TYPE_ECDSA_SECP256K1
      keychain_id: "1"
      space_id: "1"
      status: KEY_REQUEST_STATUS_PENDING
    pagination:
      total: "1"

  3. Export the request ID using the command below. Replace 1 with the actual ID you obtained.

    export KEY_REQUEST_ID=1

  4. Use the CLIChain generate command to generate the key:

    clichain generate -o private_$KEY_REQUEST_ID.key

  5. Export the public key, derived with the CLIChain public-key command:

    export PUBLIC_KEY=$(go run ./cmd/clichain public-key -k private_$KEY_REQUEST_ID.key -o base64)

  6. Fulfill the request by submitting a transaction from the Keychain Writer account:

    wardend tx warden fulfill-key-request $KEY_REQUEST_ID $PUBLIC_KEY \
      --from $KEYCHAIN_WRITER_NAME \
      --chain-id $CHAIN_ID

  7. Check the request status to make sure it was fulfilled:

    wardend query warden key-request-by-id --id=$KEY_REQUEST_ID

    Your request status will be returned in the status field of the output:

    key_request:
      creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5
      deducted_keychain_fees: []
      id: "1"
      key_type: KEY_TYPE_ECDSA_SECP256K1
      keychain_id: "1"
      space_id: "1"
      status: KEY_REQUEST_STATUS_FULFILLED

4. Fulfill a signature request​

When a user requests a signature, the Keychain signs a message with the private key and submits the signature to the chain. To test this flow, take the steps below. We'll create a signature using the key generated in the previous step.

  1. Create a signature request:

    wardend tx warden new-action new-sign-request \
      --from $KEY_NAME \
      --input "MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q=" \
      --key-id $KEY_REQUEST_ID \
      -y \
      --chain-id $CHAIN_ID \
    | wardend query wait-tx
    tip

    In the --input flag, you should provide a Base64-encoded hash. For testing purposes, you can use the hash from the example above. Alternatively, you can create one yourself – run the following command, replacing 00112233 with arbitrary raw data:

    RAW_DATA="00112233"
    HASH=$(echo -n $RAW_DATA | sha256sum | awk '{print $1}')
    BASE64_HASH=$(echo -n $HASH | xxd -r -p | base64)

    Then create a signature request. In the --input flag, specify $BASE64_HASH.

  2. Get all signature requests:

    wardend query warden sign-requests --keychain-id $KEYCHAIN_ID

    Your request ID and data for signing will be returned in the id and data_for_signing fields of the output:

    pagination:
      total: "1"
    - Result: null
      creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5
      data_for_signing: MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q=
      deducted_keychain_fees: []
      id: "1"
      key_id: "1"
      status: SIGN_REQUEST_STATUS_PENDING

  3. Export the request details using the command below. Specify the actual request ID and data you obtained.

    export DATA=MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q=
    export SIGN_REQUEST_ID=1

  4. Use the CLIChain sign command to sign the message with the key generated in the previous step. Export the signature.

    export SIGNATURE=$(echo -n $DATA | base64 -d | clichain sign -k private_$KEY_REQUEST_ID.key -o base64)

  5. Fulfill the signature request by submitting a transaction from the Keychain Writer account:

    wardend tx warden fulfill-sign-request $SIGN_REQUEST_ID $SIGNATURE \
      --from $KEYCHAIN_WRITER_NAME \
      --chain-id $CHAIN_ID

  6. Check the request status to make sure it was fulfilled:

    wardend query warden sign-request-by-id --id=$SIGN_REQUEST_ID

    Your request status will be returned in the status field of the output:

    sign_request:
    Result:
      type: SignedData
      value:
        signed_data: a0OHXtOgLHHP6qXxehlkImIjefA9fWZyuaD8hwzj4aMPiDkjvPLstu2I0+Ntcjz6wa1bh3+NGpqNKmWpqOlyiQE=
    creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5
    data_for_signing: MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q=
    deducted_keychain_fees: []
    id: "1"
    key_id: "1"
    status: SIGN_REQUEST_STATUS_FULFILLED

Next steps​

To start building a Keychain service, follow Build a Keychain app.