Skip to main content

Flare Smart Accounts CLI

The Flare Smart Accounts CLI is a tool written in Python that streamlines the Flare Smart Accounts process by properly structuring and sending XRPL transactions/instructions. It has commands corresponding to each Flare Smart Accounts action (table of instructions), as well as other useful debugging features.

note

The CLI executes only the transaction on XRPL. It does not bridge the instructions to Flare. That is done by the operator - a service that Flare runs.

To use the CLI, first clone the repository and install the necessary dependencies:

git clone https://github.com/flare-foundation/smart-accounts-cli.git
cd smart-accounts-cli
pip install -r requirements.txt

Copy the .env.example file to the .env file, and fill in the missing values in the latter.

cp .env.example .env

The missing values are an XRPL testnet account secret value, a Flare address private key, and the RPC URLs for both Flare's Coston2 and XRPL testnet. You can create a new secret string through the XRP faucets.

The script is run in the terminal with a command of the following shape.

./smart-accounts.py <command> <positional-argument> ...

Here is a list of available commands and their positional arguments:

  • encode
    • fxrp-cr: encode FXRP collateral reservation instruction
    • fxrp-transfer: encode FXRP transfer instruction
    • fxrp-redeem: encode FXRP redeem instruction
    • firelight-cr-deposit: encode Firelight collateral reservation and deposit instruction
    • firelight-deposit: encode Firelight deposit instruction
    • firelight-redeem: encode Firelight redeem instruction
    • firelight-claim-withdraw: encode Firelight claim withdraw instruction
    • upshift-cr-deposit: encode Upshift collateral reservation and deposit instruction
    • upshift-deposit: encode Upshift deposit instruction
    • upshift-request-redeem: encode Upshift request redeem instruction
    • upshift-claim: encode Upshift claim instruction
  • decode
  • bridge
    • instruction: send imputed instruction as a transaction on XRPL
    • mint-tx: make a deposit to an agent's vault

The positional arguments of the encode command correspond to type-command instruction pairs, described in the FAsset instructions guide. The bridge command either makes an XRPL Payment transaction with the imputed instruction as payment reference, or transfers funds to an agent's XRPL vault as part of the minting process.

Using the CLI​

The below-described CLI commands are intended to work in tandem with one another. The output of the encode command can be sent to the bridge command via stdin. Commands can be piped in the following way.

<encode_command> | ./smart_accounts.py bridge instruction -

If the instruction includes a minting step (fxrp-cr, firelight-cr-deposit and upshift-cr-deposit), we can also order the script to make a mint transaction that matches the output of the bridge instruction.

<encode_command> | ./smart_accounts.py bridge instruction - | ./smart_accounts.py bridge mint-tx --wait -

This is described in more detail in the Bridge section of this guide.

Encode​

Encode and instruction with given parameters. The parameters are unique to each command.

There is one parameter that all the commands have in common, walletId. The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode <command> --wallet-id <walletId> ...

FXRP​

Smart account instructions for interacting with the base FAsset system. Each of these commands starts with the fxrp keyword.

Collateral reservation​

Reserve value lots of collateral with the

Reserve value lots of FXRP to the user's smart account. The script first reserves collateral with the agent with the address, by sending a reserveCollateral instruction. It then sends a lots amount of XRP to the agent's underlying address. An executor, determined by the MasterAccountController, will complete the minting process, and lots of FXRP will be minted to the user's smart account.

The list of all the available agents and their IDs can be obtained from the MasterAccountController contract.

./smart_accounts.py encode fxrp-cr --wallet-id <walletId> --value <value> --agent-vault-id <agentVaultId>
Example values and expected output
./smart_accounts.py encode fxrp-cr --wallet-id 0 --value 1 --agent-vault-id 1

The above command produces the following output:

0x0000000000000000000000010001000000000000000000000000000000000000

Transfer​

Transfer value FXRP from your personal account to the recipientAddress on Flare. The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode fxrp-transfer \
  --wallet-id <walletId> \
  --value <value> \
  --recipient-address <recipientAddress>
Example values and expected output
./smart_accounts.py encode fxrp-transfer \
  --wallet-id 0 \
   --value 1 \
  --recipient-address "0xf5488132432118596fa13800b68df4c0ff25131d"

The above command produces the following output:

0x010000000000000000000001f5488132432118596fa13800b68df4c0ff25131d

Redeem​

Redeem value lots of FXRP back to XRP. That number of lots of FXRP are burned from the user's smart account, and the same amount of XRP is sent to the user's address on XRPL. The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode fxrp-cr --wallet-id <walletId> --value <value>
Example values and expected output
./smart_accounts.py encode fxrp-redeem --wallet-id 0 --value 1

The above command produces the following output:

0x0200000000000000000000010000000000000000000000000000000000000000

Firelight​

Smart account instructions for interacting with a Firelight-type vault. Each of these commands starts with the firelight keyword.

Collateral reservation and deposit​

The collateral reservation and deposit instruction signals two intents at once. First, to reserve collateral in an agent's vault, registered with the MasterAccountController contract with the agentVaultId, the necessary collateral to mint value lots of FXRP. And second, to deposit the newly minted FXRP into a Firelight-type vault, registered with the MasterAccountController contract with the vaultId.

The purpose of this instruction is to streamline the minting and deposit process by cutting out an instruction XRPL transaction and the wait that that incurs. In essence, it combines the FXRP collateral reservation instruction and the Firelight deposit instruction.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode firelight-cr-deposit \
 --wallet-id <walletId> \
 --value <value> \
 --agent-vault-id <agentVaultId> \
 --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode firelight-cr-deposit --wallet-id 0 --value 1 --agent-vault-id 1 --vault-id 1

The above command produces the following output:

0x1000000000000000000000010001000100000000000000000000000000000000

Deposit​

Deposit vault drops of FXRP into the Firelight-type vault, registered with the MasterAccountController contract with the vaultId. The complete list of the registered vaults can be obtained from the MasterAccountController contract.

warning

The registered vaults can be of either the Firelight- or Upshift-type, so make sure that you choose the right one for the instruction you are sending.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode firelight-deposit --wallet-id <walletId> --value <value> --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode firelight-deposit --wallet-id 0 --value 1 --vault-id 1

The above command produces the following output:

0x1100000000000000000000010000000100000000000000000000000000000000

Redeem​

Begin the withdrawal process from the Firelight-type vault. A value of drops FXRP is marked to be withdrawn from the Firelight-type vault, registered with the MasterAccountController contract with the vaultId, to the user's personal account.

In the process, the vault emits an event with the period parameter. This value is required in the second part of the withdrawal process.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode firelight-redeem --wallet-id <walletId> --value <value> --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode firelight-redeem --wallet-id 0 --value 1 --vault-id 1

The above command produces the following output:

0x1200000000000000000000010000000100000000000000000000000000000000

Claim withdraw​

Complete the withdrawal process from the Firelight-type vault, registered with the MasterAccountController contract with the vaultId. After the withdrawal process has been started, the funds are locked for a certain amount of time. Once that period has passed, they can be transferred back to the user's personal account.

When the withdrawal is requested, a period value is exposed in the event that is emitted. The period must be included in the claim withdrawal instruction as the value parameter.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode firelight-claim-withdraw \
  --wallet-id <walletId> \
  --value <value> \
  --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode firelight-claim-withdraw --wallet-id 0 --value 123456789 --vault-id 1

The above command produces the following output:

0x1300000000000000075bcd150000000100000000000000000000000000000000

Upshift​

Smart account instructions for interacting with an Upshift-type vault. Each of these commands starts with the upshift keyword.

Collateral reservation and deposit​

The collateral reservation and deposit instruction signals two intents at once. First, to reserve collateral in an agent's vault, registered with the MasterAccountController contract with the agentVaultId, the necessary collateral to mint value lots of FXRP. And second, to deposit the newly minted FXRP into an Upshift-type vault, registered with the MasterAccountController contract with the vaultId.

The purpose of this instruction is to streamline the minting and deposit process by cutting out an instruction XRPL transaction and the wait that that incurs. In essence, it combines the FXRP collateral reservation instruction and the Upshift deposit instruction.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode upshift-cr-deposit \
 --wallet-id <walletId> \
 --value <value> \
 --agent-vault-id <agentVaultId> \
 --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode upshift-cr-deposit --wallet-id 0 --value 1 --agent-vault-id 1 --vault-id 2

The above command produces the following output:

0x2000000000000000000000010001000200000000000000000000000000000000

Deposit​

Deposit vault drops of FXRP into the Upshift-type vault, registered with the MasterAccountController contract with the vaultId. The complete list of the registered vaults can be obtained from the MasterAccountController contract.

warning

The registered vaults can be of either the Firelight- or Upshift-type, so make sure that you choose the right one for the instruction you are sending.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode upshift-deposit --wallet-id <walletId> --value <value> --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode upshift-deposit --wallet-id 0 --value 1 --vault-id 2

The above command produces the following output:

0x2100000000000000000000010000000200000000000000000000000000000000

Request redeem​

Begin the withdrawal process from an Upshift-type vault. A value of drops FXRP is marked to be withdrawn from the Upshift-type vault, registered with the MasterAccountController contract with the vaultId, to the user's personal account.

In the process, the vault emits an event with the period parameter. This value is required in the second part of the withdrawal process.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode upshift-request-redeem \
  --wallet-id <walletId> \
  --value <value> \
  --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode upshift-request-redeem --wallet-id 0 --value 1 --vault-id 2

The above command produces the following output:

0x2200000000000000000000010000000200000000000000000000000000000000

Claim​

Complete the withdrawal process from the Upshift-type vault, registered with the MasterAccountController contract with the vaultId. After the withdrawal process has been started, the funds are locked for a certain amount of time. Once that period has passed, they can be transferred back to the user's personal account.

The value parameter is the date when the redemption was requested. It should be given as an 8-digit number YYYYMMDD, where YYYY is the year, MM the month (from 1 to 12) and DD (from 1 to 31) the day of the redemption request.

The walletId is a Flare-designated parameter, intended for wallet identification by the operator. It has no impact on the result of the action performed. If no number has been provided to you, set the walletId to 0.

./smart_accounts.py encode upshift-redeem --wallet-id <walletId> --value <value> --vault-id <vaultId>
Example values and expected output
./smart_accounts.py encode upshift-claim --wallet-id 0 --value 20260124 --vault-id 2

The above command produces the following output:

0x23000000000000000135251c0000000200000000000000000000000000000000

Bridge​

The bridge command makes an XRPL Payment transaction on behalf of the user, with the given input as the transaction memo field. There are two positional arguments, instruction and mint-tx. The instruction positional argument signals the user's intent by making an XRPL Payment transaction to the operator's XRPL address, with the instruction attached as the memo field. The mint-tx argument performs the second step of the minting process, sending the XRPL to the agent's vault address on XRPL (you can learn more about the minting process in the minting guide).

Instruction​

When the bridge command is used with the instruction positional argument, it accepts an encodedInstruction as input. It makes a Payment transaction to the operator's XRPL address, with the encodedInstruction as the memo field of the payment. Finally, it prints the hash of the transaction to the standard output stream.

The encodedInstruction can be obtained with the encode command.

./smart_accounts.py bridge instruction <encodedInstruction>

Alternatively, the command can read the input directly from the standard input stream. Since the encode command prints the result to the standard output stream, the two commands can be chained together. To do this, the - character is used instead of the transactionHash.

<encode_command> | ./smart_accounts.py bridge instruction -
Example values and expected output
./smart_accounts.py encode fxrp-redeem --wallet-id 0 --value 1 \
  | ./smart_accounts.py bridge instruction -

The above command encodes an FXRP redeem instruction for 1 lot of FXRP, and sends that instruction as an XRPL Payment transaction. It produces the following output.

sent bridge instruction transaction: CD0879CD7398DE4B96A7A7D475EFD0F3585E05D100C84C9E3FE32B34FACF0E39
CD0879CD7398DE4B96A7A7D475EFD0F3585E05D100C84C9E3FE32B34FACF0E39

The instruction only works if the user's personal account has sufficient FXRP balance.

Mint tx​

When the bridge command is used with the mint-tx positional argument, it accepts an XRPL transactionHash as input. It then observes the MasterAccountController contract for a CollateralReserved event that belongs to the transaction with the transactionHash A payment reference is read from the CollateralReserved event, and a mint transaction to the agent vault's address is performed.

The transaction must contain a collateral reservation (and deposit) instruction, otherwise the process fails, since no such event is emitted for other instructions.

The transactionHash can be obtained by calling the bridge command with the instruction positional argument.

./smart_accounts.py bridge mint-tx <transactionHash>

Alternatively, the command can read the input directly from the standard input stream. Since the encode and bridge commands both print the result to the standard output stream, all three commands can be chained together. To do this, the - character is used instead of the transactionHash. Additionally, the --wait flag must be provided.

<encode_command> | ./smart_accounts.py bridge instruction - | ./smart_accounts.py bridge mint-tx --wait -
Example values and expected output
./smart_accounts.py encode fxrp-cr --wallet-id 0 --value 1 --agent-vault-id 1 \
  | ./smart_accounts.py bridge instruction - \
  | ./smart_accounts.py bridge mint-tx --wait -

The above command encodes an FXRP collateral reservation instruction for 1 lot of FXRP, using the agent vault with ID 1, and sends that instruction as an XRPL Payment transaction. It then waits It produces the following output.

sent bridge instruction transaction: 659364520199DED473635A9ABFB1C15B945B216A1208679979AB5C05F03E837C
sent mint tx: 8401244DD1FA4C295ABC16A0B05CC12F7DBCE34756F12C2F5C3DC1840A5F3316
8401244DD1FA4C295ABC16A0B05CC12F7DBCE34756F12C2F5C3DC1840A5F3316

The instruction only works if the user's personal account has sufficient FXRP balance.

Decode​

The decode command is the inverse of the encode command. It takes an encodedInstruction as input, and decodes it to a Python class that corresponds to the instruction. The encodedInstruction can be obtained from the output of the encode command.

./smart_accounts.py decode <encodedInstruction>

Alternatively, the command can read the input directly from the standard input stream. Since the encode command prints the result to the standard output stream, the two commands can be chained together. To do this, the - character is used instead of the transactionHash.

<encode_command> | ./smart_accounts.py decode -
Example values and expected output
./smart_accounts.py encode fxrp-redeem --wallet-id 0 --value 1 \
  | ./smart_accounts.py decode -

The above command encodes an FXRP redeem instruction for 1 lot of FXRP, and then decodes it to an FxrpRedeem class. It produces the following output.

FxrpRedeem(wallet_id=0, value=1)