​
Basic wallet operations

In this sections, you’ll use Wallets to model the basics RPG game mechanisms. You’ll manage the wallet of Eryldor, an elf mage living countless adventures!

​
An introduction to Wallets

At its core, a wallet is a container of assets related to one entity. It can be used to store and manage any kind of assets, from money to items, and even more complex objects. In the context of Cones of Dunshires, a wallet is used to store the money, currencies, and points of a character. A wallet is composed of balances. A balance is a mechanism to logically separate assets according to nature, usage, lifecycle or any other criteria. A balance can be seen as a sub-wallet, and can be used to store and manage a specific set of assets. A balance can expire. When a balance expires, its assets cannot be used anymore. In Cones of Dunshires, Eryldor has a wallet with two balances: one for coins and experience points, and another for badges, which are earned in tournaments and expire when the tournament season ends. Here is the structure of Eryldor’s wallet.
Erlydor's wallet structure

​
Creating Eryldor’s wallet

Before starting, make sure you have followed the prequisities and that you’re logged with the fctl login command.
First you’ll create Eryldor’s wallet. You’ll use the fctl wallet create command to create a wallet named eryldor. 
fctl wallets create eryldor
You’ll get a response like this: 
You are about to create a wallet.
Do you want to continue [Y/n]: y
 SUCCESS  Wallet created successfully with ID: 9d21fd84-xxxx-yyyy-zzzz-250aaa73b374
Wallets come with a default balance named main. You can use it to store and manage assets without creating additional balances. Here, you’ll use the main balance to store and manage the coins and experience points of Eryldor.

​
Create the season-2024 balance

Now you’ll create a balance named season-2024 to store the badges of Eryldor. This balance will expire at the end of the tournament season 2024. Here it will expire on January 1st, 2025.
Feel free to adapt the expiration date to your needs.
fctl wallets balances create season-2024 --name eryldor --expires-at "2025-01-01T00:00:00Z"
You’ll get a response like this: 
 SUCCESS  Balance created successfully with name: season-2024

​
Inspecting Eryldor’s wallet

You can inspect the wallet in the Formance Console. First open the console. 
fctl ui
Then navigate to the Wallets section and select the eryldor wallet. You’ll see the main balance and the season-2024 balance as shown in the screenshot below.
Eryldor's wallet in the Formance Console
A common use case for balances is to model vouchers, coupons, or any kind of assets that have a limited lifecycle. For example, you can create a balance for each voucher type, and set the expiration date to the end of the voucher validity period.

​
Crediting Eryldor with coins and experience points

After tremendous adventures, Eryldor managed to complete their first quest! As a well-deserved reward, they earned 10 COIN and 150 experience points. You’ll use the fctl wallets credit command to credit Eryldor’s wallet with these assets. When you credit a wallet, you must specify where does the funds come from. Here, you’ll specify that the funds come from the account world. world is a special account that represents the external world, and is used to introduce or remove assets from the system. Note that you didn’t specify a balance. When you don’t specify a balance, the main balance is used by default as it is the primary balance of the wallet. Add the coins 
fctl wallets credit 10 COIN --name eryldor --source account=world
Add the experience points 
fctl wallets credit 150 XP --name eryldor --source account=world
If you specify a source different from world, you’ll get an INSUFFICIENT_FUND error. This is because you can only credit a wallet with assets coming from either the external world or another wallet.

​
Inspecting Eryldor’s wallet

Let’s inspect Eryldor’s wallet in the Formance Console. You’ll see that the main balance contains 10 COIN and 150 XP, as shown in the screenshot below.
Eryldor's wallet in the Formance Console

​
Debiting Eryldor’s wallet

Eryldor is now ready to buy a new spellbook! They found a rare spellbook for 5 COIN! It is a very good deal, so they decide to buy it. You’ll use the fctl wallets debit command to debit Eryldor’s wallet with 5 COIN. 
fctl wallet debit 5 COIN --name eryldor --destination account=world
You’ll get a response like this: 
 SUCCESS  Wallet debited successfully!
As we did for the credit, you must specify the destination of the funds. Here, you specify that the funds go to the account world. world being a special account that represents the external world, it can also be used to remove assets from the system.

​
Inspecting Eryldor’s wallet

Let’s inspect Eryldor’s wallet in the Formance Console. You’ll see that the main balance contains 5 COIN and 150 XP, as shown in the screenshot below.
Eryldor's wallet in the Formance Console

​
Earning badges

Eryldor is a very skilled mage and they are participating in the tournament season 2024. Thanks to their new spellbook, they managed to win the first tournament and earned a badge! Badges are earned in tournaments and expire at the end of the tournament season. You’ll use the fctl wallets credit command to credit Eryldor’s wallet with a badge. It’s a special asset that you’ll represent with the BADGE currency. The process is the same as for the coins and experience points, with the difference that you’ll specify the season-2024 balance. 
fctl wallets credit 1 BADGE --name eryldor --balance season-2024 --source account=world
You’ll get a response like this: 
 SUCCESS  Wallet credited successfully!

​
Inspecting Eryldor’s wallet

Let’s inspect Eryldor’s wallet in the Formance Console. You’ll see that the season-2024 balance contains 1 BADGE, as shown in the screenshot below.
Eryldor's wallet in the Formance Console

​
Next steps

In this section, you’ve learned how to create a wallet, create balances, credit and debit a wallet, and credit a balance. You’ve also learned how to inspect a wallet in the Formance Console. In the next session, you’ll learn how to use the Wallets to model a hold, a mechanism to freeze assets for a specific purpose, such as a deposit or a reservation.