14.12. libeufin-sandbox(1)¶
14.12.1. Name¶
libeufin-sandbox - Simulate a banking system core with EBICS access to bank accounts
14.12.2. Synopsis¶
libeufin-sandbox [-h | –help] [–version] COMMAND [ARGS…]
Commands: serve, reset-tables, config, make-transaction, camt053tick default-exchange
14.12.3. Description¶
libeufin-sandbox is a program to simulate a banking system core with EBICS access to bank accounts. It maintains state in its own private database. You interact with it through HTTP requests either over the network or via a Unix domain socket. Related program libeufin-cli is the preferred front end for that mode of operation. There is also a mode where libeufin-sandbox accepts commands directly, useful for configuring one or more “demobank” (simulated bank) instances.
Its options are as follows:
- -h | –help
Print short help on options.
- –version
Print version information.
The interaction model is as follows:
Configure the sandbox with commands
config
,default-exchange
,make-transaction
, andcamt053tick
.Start the HTTP server with command
serve
. Let this run in a shell, writing logs to stderr.Point program libeufin-nexus at the sandbox.
Interact with libeufin-nexus.
When finished, interrupt the
serve
process and clean up with commandreset-tables
.
The following sections describe each command in detail.
14.12.3.1. config¶
This command takes argument NAME
and creates a demobank with that name.
Option --currency CUR
(default: EUR
) specifes another currency.
Option --captcha-url $URL
specifies where the wallet user is going
to be redirected to confirm the withdrawal operation. This $URL should
point to the bank frontend. More precisely to the UI that let the user
finish a withdrawal operation that needs to be confirmed. Example of
this value may be “https://bank.domain/#/operation/{wopid}” where
“https://bank.domain” returns the demobank SPA and the demobank view under
the route “/operation/{wopid}” will show the status of the operation id {wopid}.
Note that “{wopid}” is literally in the –captcha-url config and replaced at
runtime by the sandbox server.
Option --bank-debt-limit N
(default: 1000000) specifies that
the bank debt limit should be N (units of currency).
Similarly, option --users-debt-limit N
(default: 1000) specifies
that the users debt limit should be N (units of currency).
For example:
$ libeufin-sandbox config default
This creates the demobank default
with currency EUR
,
bank debt limit 1000000, users debt limit 1000,
and allows registrations.
14.12.3.2. default-exchange¶
This command sets the exchange that a demobank will suggest to wallets.
(Wallets are of course free to disregard the suggestion and choose
another exchange.)
It requires two arguments, EXCHANGE-BASEURL
and EXCHANGE-PAYTO
.
The option --demobank NAME
(default: default
) specifies
which demobank this setting affects.
For example:
$ libeufin-sandbox default-exchange \
--demobank bank01 \
https://exchange.example.com/ \
payto://iban/CH9300762011623852957
This sets the default exchange for demobank bank01
.
It is an error if the demobank does not exist.
14.12.3.3. make-transaction¶
This is a “legacy” command, useful in a previous iteration of LibEuFin and for internal testing. It creates and records a wire transfer transaction in the database.
It takes two arguments and several required options.
The arguments are AMOUNT
, in CUR:X.Y
format;
and SUBJECT
, a short textual description of the transaction.
The options are: --credit-account LABEL
and --debit-account LABEL
,
where each LABEL names a bank account for receiving and issuing,
respectively, the wire transfer.
The option --demobank NAME
(default: default
) specifies
in which demobank the wire transfer occurs.
Note
If you have not yet called config
, this command creates
a demobank named default
on its first use. The currency,
and bank debt limit have the same defaults as for the config
command. The users debt limit, however, defaults to 10000.
FIXME: How to achieve the same result with libeufin-cli?
14.12.3.4. camt053tick¶
This command advances the internal time step that the demobank uses to group transactions for reporting. (Successive transactions will be inserted in a new Camt.053 report.)
For example:
$ libeufin-sandbox camt053tick
FIXME: How to achieve the same result with libeufin-cli?
14.12.3.5. serve¶
This command starts the HTTP server, listening on port 5000.
To use a different port, use option --port INT
.
To listen, instead, on a Unix domain socket,
use option --with-unix-socket PATH
.
When both --port
and --with-unix-socket
are given,
--with-unix-socket
takes precedence.
Note
If you have not yet called config
, this command creates
a demobank named default
on its first use. The currency,
and bank debt limit have the same defaults as for the config
command. The users debt limit, however, defaults to 10000.
The process runs in the foreground, writing its logs to standard error.
The normal log level is DEBUG
.
To change it, use --log-level LEVEL
, where LEVEL
is one of:
ERROR
, WARN
, INFO
, DEBUG
, TRACE
.
Before invoking serve
, the following environment variables need to be set:
LIBEUFIN_SANDBOX_ADMIN_PASSWORD
The password required for later use by libeufin-cli. For testing purposes, you can use option
--no-auth
to disable this requirement. (In that case, this environment variable need not be set.)LIBEUFIN_SANDBOX_DB_CONNECTION
This specifies the database libeufin-sandbox uses to maintain state. Currently, both Sqlite and PostgreSQL are supported. (Only one needs to be specified.) Examples:
jdbc:sqlite:/tmp/libeufin-sandbox.db
jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret
Normally, the serve
command runs until interrupted.
When run in a shell, you can use Control-C
for that.
14.12.3.6. reset-tables¶
This command drops all the tables in the internal database. (The next time the tables are needed, libeufin-sandbox creates them again, automatically.)
It should only be used when the sandbox is quiescent.
14.12.4. See Also¶
14.12.5. Bugs¶
Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.