Encrypted Transactions

All code in this tutorial is purely educational. It is up to the reader’s discretion to build their applications following industry standards, practices, and applicable regulations.

This tutorial focuses on simple IBE-MPC encrypted transactions, using a target block height as the condition for automatic decryption and execution. Fairblock offers various MPC schemes for fun and novel dynamic confidential computation. Our main MPC scheme it offers is threshold IBE, where the FairyRing network is used to generate public keys for encryption and their respective decryption keys, based on a specific id, otherwise referred to as a “condition.” This tutorial will guide you through using a simple Bash script to encrypt and send transactions in Fairblock with execution conditions based on a specific block height. The repo can be found here.

Conditions can take the shape of anything, be it the price of an asset, interest rates, etc.

By default, apps developed on FairyRing can use FairyRing block height as the specific condition at which the respective decryption key will be generated to decrypt and trigger execution for a encrypted transaction. The encrypted messages within this tutorial are referred to, for lack of better term, as a “bank msg” where one sends tokens and a memo, all of which are encrypted. By the end, you’ll understand how to:

Send encrypted messages and token transfers using FairyRing and its inherent functionalities, leveraging aspects such as the x/pep module. More specifically:
- Create and sign transactions on Fairblock
- Encrypt transactions for deferred execution
- Retrieve transaction status and results
Extract specific information from the decrypted messages using FairyRing. This information can be useful for creating your own specific apps leveraging this small sample of confidential computation possibilities.

A quick walk through of this demo is show in the video below. Feel free to watch it and follow along with the rest of this page. Please note that this page goes through the details of the demo, check out the “Start a cApp in 5 Minutes” section if you want a shorter version.

Demo Quick Start

To run this demo, simply download this repo, and switch to this specific feature branch, feat-auction.

git clone https://github.com/Fairblock/fairyring.git
cd fairyring
git checkout feat-auction

Now, simply run:

make devnet-up
./bankMsgWithMemoAndDecryption.sh

Upon running the ./bankMsgWithMemoAndDecryption.sh script, you will be prompted for the following basic inputs required to:

Specify the recipient of said bank message,
Encrypt the message with a target block height,
Submit the encrypted transaction to the blockchain,
Monitor the network for transaction processing, and show the decrypted result

Demo Details

The provided bash script, bankMsgWithMemoAndDecryption.sh, does the following:

Step	Description
Takes User Input	Asks for a FairyRing recipient address, the amount of uFairy to transfer, the wallet account name sending funds, and a note for the transaction that acts as the message to be encrypted.
Gets Required Info	Fetches your public key, account address, account number, and sequence number from the list of devwallets available for the demo dev net.
Creates a Transaction	Generates an unsigned transaction with the specified details.
Signs the Transaction	Uses the specified account’s dev net credentials to sign it securely.
Uses `x/pep` Module to Encrypt the Transaction	Uses the standard convention of encrypting a message.
Submits the Encrypted Transaction	Sends it to the local devnet.
Waits for Confirmation	Watches the local FairyRing devnet blockchain height and checks when your transaction is included.
Lists Decrypted Transactions	Once confirmed, it retrieves and displays the decrypted transaction.

Through using the FairyRing network, the following perks for said transaction are achieved:

Transaction details private using encryption.
Ensures proper signing so transactions are valid.
The script making it easy to interact with the FairyRing blockchain while keeping your transactions private!

Frequently Used CLI Commands

The output decrypted data is in JSON format. Developers are encouraged to parse the encrypted message for whatever data they may need for their own app design. This is where the true creative freedom comes into play! The following are CLI commands one can use within their own scripts to work with encrypted transactions at a rudimental level, including extracting information as needed. Expand the toggle to see its details. There are numerous ways to work with JSON files, we simply use jq within the following CLI commands shown and our demo script within this repo. See the official jq download docs here.

Commonly used CLI commands shown in this tutorial

Fetch the Public Key for Encryption

Use this in your app if you need to encrypt messages or transactions.

fairyringd query pep show-active-pub-key -o json | jq -r '.active_pubkey.public_key'

Getting a FairyRing Account Address

Essential if you’re writing a wallet integration.

fairyringd keys show $ACCOUNT_NAME -a --keyring-backend test --home devnet_data/fairyring_devnet

Create an Unsigned Transaction

Builds a raw transaction JSON to be signed afterwards.

fairyringd tx bank send $ACC_ADDR $RECIPIENT $AMOUNT --generate-only -o json

Get Account Number (for offline signing)

Your application might need this if it manually constructs and signs transactions.

fairyringd query auth account $ACC_ADDR -o json | jq -r '.account.value.account_number'

Get Sequence Number (Nonce)

Obtaining the nonce is helpful when signing to prevent replay attacks.

fairyringd query pep show-pep-nonce $ACC_ADDR -o json | jq -r '.pep_nonce.nonce'

Signs the Transaction Locally

This allows offline signing, useful for hardware wallets or remote signing services.

If your app needs to handle user signing, it can call:

fairyringd tx sign unsigned.json --from $ACCOUNT_NAME --offline --account-number $ACC_NUM --sequence $ACC_SEQ

Encrypting the Signed Transaction

Use the following to actually encrypt the transaction where one has to specify the target height, respective public key, and signed transaction.

fairyringd encrypt $TARGET_HEIGHT $PUBKEY "$SIGNED"

Submitting the Encrypted Transaction:

Use the below command to submit the encrypted transaction with a specified target height for decryption.

fairyringd tx pep submit-encrypted-tx $ENCRYPTED $TARGET_HEIGHT

Extracting the Transaction Hash (For Tracking)

Use the below command to extract the transaction hash that can be used to monitor the transaction status.

echo "$TX_SUBMISSION_OUTPUT" | grep -oE "txhash: [A-Fa-f0-9]+" | awk '{print $2}'

Wait for Confirmation & Retrieves the Decrypted Transaction

This command monitors block height until the transaction is executed, and fetches decrypted transactions for further processing:

This can be used to display decrypted transaction details in your app.

fairyringd list-decrypted-txs $TARGET_HEIGHT --output json | jq

How You Can Use These Commands in Your Own App

Build your own app that uses the rudimentary encrypted transaction functionality with FairyRing.
Automate transaction workflows → Utilize contract call-back, and thus fetch and process decrypted transactions once confirmed automatically.
Build a transaction explorer → Extract TX hashes and track status.

Next Steps

Congratulations! You have now seen an example of encrypting a transaction with a message and transfer amount. There are several next steps you can take now anon.

Check out the actual time bomb demo app on the FairyRing testnet here.
Check out our other quick starts to see how to build with other networks integrating into FairyRing in the Quick Start.
Join our discord and discuss new build ideas! We host frequent developer hours to encourage more novel ideas with confidential computation.

Further tutorials will be shared to showcase how to create more generic applications using general conditions instead of the default block height condition id used currently within FairyRing.

Encrypt transactions for `x/pep` module

This tutorial explains how to encrypt your transaction for the x/pep module using the encrypter built into fairyringd. Ensure you have installed the fairyring binary before following the instructions below. This section focuses on simple IBE-MPC encrypted transactions, using a target block height as the condition for automatic decryption and execution.

Encrypt your transaction

Getting the public key for encryption

PUBKEY=$(fairyringd query pep show-active-pub-key | jq -r '.active_pubkey.public_key')

Create the signed transaction. We’ll use a bank send transaction in this example.

fairyringd tx bank send [FROM_ADDRESS] [TO_ADDRESS] [AMOUNT] --from [YOUR_ACCOUNT_NAME] --gas-prices 1ufairy --generate-only -o json -y > unsigned.json

[FROM_ADDRESS] is the address you are using to send the token.
[TO_ADDRESS] is the recipient address.
[AMOUNT] is the amount you would like to send.
[YOUR_ACCOUNT_NAME] is the account name of your [FROM_ADDRESS].
--gas-prices is the gas price you are paying.
--generate-only means you only generate the unsigned transaction.
-o json means to output the unsigned transaction in json format.
> unsigned.json means outputs the unsigned transaction to a file named unsigned.json.

Example:

fairyringd tx bank send fairy18hl5c9xn5dze2g50uaw0l2mr02ew57zkynp0td fairy1qnk2n4nlkpw9xfqntladh74w6ujtulwnsgww3g 100ufairy --from alice --gas-prices 1ufairy --generate-only -o json -y > unsigned.json

This corresponds to a transaction that sends 100ufairy from alice (fairy18hl5c9xn5dze2g50uaw0l2mr02ew57zkynp0td) to fairy1qnk2n4nlkpw9xfqntladh74w6ujtulwnsgww3g. The unsigned.json looks something like this:

{
 "body": {
  "messages": [
   {
    "@type": "/cosmos.bank.v1beta1.MsgSend",
    "from_address": "fairy18hl5c9xn5dze2g50uaw0l2mr02ew57zkynp0td",
    "to_address": "fairy1qnk2n4nlkpw9xfqntladh74w6ujtulwnsgww3g",
    "amount": [{ "denom": "ufairy", "amount": "100" }]
   }
  ],
  "memo": "",
  "timeout_height": "0",
  "extension_options": [],
  "non_critical_extension_options": []
 },
 "auth_info": {
  "signer_infos": [],
  "fee": {
   "amount": [{ "denom": "ufairy", "amount": "200000" }],
   "gas_limit": "200000",
   "payer": "",
   "granter": ""
  },
  "tip": null
 },
 "signatures": []
}

Signing the transaction

SIGNED=$(fairyringd tx sign unsigned.json --from [ACCOUNT_NAME] --offline \
--account-number $(fairyringd query account $(fairyringd keys show [ACCOUNT_NAME] -a) -o json | jq -r '.account_number') \
--sequence $(fairyringd query pep show-pep-nonce $(fairyringd keys show [ACCOUNT_NAME] -a) -o json | jq -r '.pepNonce.nonce'))

[ACCOUNT_NAME] replace all instances to the account name you are using to sign the transaction.
--offline means that you are signing your transaction offline with the provided account number & sequence instead of fetching it from the chain.
--account-number is your account number, the command above will fetch it for you automatically.
--sequence is the pep nonce of your address, the command above will fetch it for you automatically.

Example:

SIGNED=$(fairyringd tx sign unsigned.json --from alice --offline \
--account-number $(fairyringd query account $(fairyringd keys show alice -a) -o json | jq -r '.account_number') \
--sequence $(fairyringd query pep show-pep-nonce $(fairyringd keys show alice -a) -o json | jq -r '.pepNonce.nonce'))

The signed transaction looks like this:

{
 "body": {
  "messages": [
   {
    "@type": "/cosmos.bank.v1beta1.MsgSend",
    "from_address": "fairy18hl5c9xn5dze2g50uaw0l2mr02ew57zkynp0td",
    "to_address": "fairy1qnk2n4nlkpw9xfqntladh74w6ujtulwnsgww3g",
    "amount": [{ "denom": "ufairy", "amount": "100" }]
   }
  ],
  "memo": "",
  "timeout_height": "0",
  "extension_options": [],
  "non_critical_extension_options": []
 },
 "auth_info": {
  "signer_infos": [
   {
    "public_key": {
     "@type": "/cosmos.crypto.secp256k1.PubKey",
     "key": "A3wiGqD+PZYB+hgRmWbD3Sugv2Ofw3G7rFjT0PJ7SBIZ"
    },
    "mode_info": { "single": { "mode": "SIGN_MODE_DIRECT" } },
    "sequence": "3"
   }
  ],
  "fee": {
   "amount": [{ "denom": "ufairy", "amount": "200000" }],
   "gas_limit": "200000",
   "payer": "",
   "granter": ""
  },
  "tip": null
 },
 "signatures": [
  "vmPWsuAsasg...10Ad2QafEByg2q0zug=="
 ]
}

You can check your signed transaction with the following command: echo $SIGNED | jq

Encrypting the transaction

ENCRYPTED=$(fairyringd encrypt [TARGET_HEIGHT / REQ-ID] $PUBKEY $SIGNED)

[TARGET_HEIGHT / REQ-ID] is the target execution height of your transaction, or if you are encrypting a general tx, it is the request id / identity. It will also be used when you submit the encrypted transaction.
$PUBKEY is the public key (encryption key) you got from Step 1.
$SIGNED is the signed transaction from Step 3.

Check the encrypted transaction by:

echo $ENCRYPTED

Submit the encrypted transaction

fairyringd tx pep submit-encrypted-tx $ENCRYPTED [TARGET_HEIGHT] --from [ACCOUNT_NAME] --gas-prices 1ufairy -y

$ENCRYPTED is the hex encoded encrypted tx from encrypter
[TARGET_HEIGHT] is the target execution height of your transaction. This should be the same as the [TARGET_HEIGHT] used when encrypting the transaction using encrypter
[ACCOUNT_NAME] is the account you would like to send the transaction from. This should be the same as the account you used to sign the transaction.

If you are submitting a general encrypted transaction:

fairyringd tx pep submit-general-encrypted-tx $ENCRYPTED [REQ-ID] --from [ACCOUNT_NAME] --gas-prices 1ufairy -y

$ENCRYPTED is the hex encoded encrypted tx from encrypter
[REQ-ID] is the request id / identity used in encryption. This should be the same as the [REQ-ID] used when encrypting the transaction using encrypter
[ACCOUNT_NAME] is the account you would like to send the transaction from. This should be the same as the account you used to sign the transaction.

​Demo Quick Start

​Demo Details

​Frequently Used CLI Commands

​Fetch the Public Key for Encryption

​Getting a FairyRing Account Address

​Create an Unsigned Transaction

​Get Account Number (for offline signing)

​Get Sequence Number (Nonce)

​Signs the Transaction Locally

​Encrypting the Signed Transaction

​Submitting the Encrypted Transaction:

​Extracting the Transaction Hash (For Tracking)

​Wait for Confirmation & Retrieves the Decrypted Transaction

​How You Can Use These Commands in Your Own App

​Next Steps

​Encrypt transactions for x/pep module

​Encrypt your transaction

Demo Quick Start

Demo Details

Frequently Used CLI Commands

Fetch the Public Key for Encryption

Getting a FairyRing Account Address

Create an Unsigned Transaction

Get Account Number (for offline signing)

Get Sequence Number (Nonce)

Signs the Transaction Locally

Encrypting the Signed Transaction

Submitting the Encrypted Transaction:

Extracting the Transaction Hash (For Tracking)

Wait for Confirmation & Retrieves the Decrypted Transaction

How You Can Use These Commands in Your Own App

Next Steps

Encrypt transactions for `x/pep` module

Encrypt your transaction