Skip to main content

Introducing money into the ledger

Now you have Formance Ledger up and ready to accept transactions. Woohoo! Let's get started by creating our first transaction in Numscript.

Right now, your coffers in the game world of Cones of Dunshire are entirely empty. We need to seed it with a little coin so that we can distribute it to players.

Of course, in the real world, we can't just create money. Money enters our accounts from the outside world, and we need a way to track that in our ledger. We do this through a special account called @world. This account represents the world outside of our system. It is unique in that it can never be overdrawn (unlike other accounts). This allows us to represent movements of money into our system by transferring money from the @world account to the account that actually received the money.

So, to introduce coin into our game world of Cones of Dunshire, we'll need to transfer money from @world into our administrative central account. From there, we can start circulating it throughout Dunshire in various waysโ€”we'll get to that soon.

Introducing new coin with Numscriptโ€‹

We begin by introducing new coin into the world, by transfering it from @world to @centralbank.

Create a file called intro.num with the following Numscript:

This bit of Numscript encodes a transaction. A transaction is a description of a quantity of money sent from a source account to a destination account.

  • [COIN 100] means we want to send 100 coins. You can send money in whatever currency makes sense for your use case. Very often this will be USD or EUR. (We'll talk more about sending fractions of a unit of currency in a bit).

  • source = @world means the source of the money is the external worldโ€”we are introducing money into the ledger.

  • destination = @centralbank means the money should go to our @centralbank account. In our case, we just want a central store for Dunshire coin, but in your situation you might have multiple accounts that can receive money from. You can name these accounts however you like.


You don't have to have a @centralbank account, this is just an example designed to keep things simple. In your case, payments might land in a variety of accounts. This is no problem. You can transfer money from @world into any account.

Executing the Numscriptโ€‹

OK, we have our transaction described with Numscript. How do we execute the transaction against our ledger? We need to feed the Numscript to our running instance of Formance Ledger.

numary exec dunshire intro.num

Formance Ledger can track money movements through multiple distinct ledgers. Each ledger has a name, and each transaction must be assigned to a specific ledger. In many cases, you'll only need one ledger. Sometimes though you might want more than one. In this example, we instructed Formance Ledger to use the dunshire ledger for the transaction. That ledger didn't previously exist, so Formance Ledger helpfully created it for us. We'll continue to use the dunshire ledger throughout the docs.

If all goes well, you should see:

Script ran successfully โœ…

Congratulations! You've now got money in your ledger.


Otherwise, if you see something like:

FATA[0000] Post "http://localhost:3068/dunshire/script": dial tcp [::1]:3068: connect: connection refused

then the Formance Ledger service isn't running. Make sure the server is running.

Next stepsโ€‹

In the next step, we're going to verify that the coin was indeed introduced into the proper account.