Docs/Get startedv0.0.1-preview

Quickstart

A running ledger, a first transfer, and proof of idempotency — on one Linux server or a Mac, with the TulaDB installer and tulactl.

On this page
  1. 1. Install and start a node
  2. 2. Create a ledger and two accounts
  3. 3. First transfer
  4. 4. Try to double-post
  5. 5. Read it back
  6. 6. Check the node, then tear down
  7. Where next

This walkthrough installs TulaDB, then moves value and proves the idempotency guarantee by trying to post the same transfer twice. You need one supported Linux server (or a Mac, for a development install) and the installer from Downloads. Nothing else needs to be installed first.

Availability: the 0.0.1-preview installers are on Downloads (downloads.tuladb.com/core/0.0.1-preview/), signed and verifiable offline. To try the whole stack in containers instead, with Docker or Podman, see the developer quick setup.

1. Install and start a node

Verify the download first (see Download and verify). Then:

chmod +x tuladb-installer-0.0.1-preview-linux-x86_64
sudo ./tuladb-installer-0.0.1-preview-linux-x86_64 install --single

The installer installs the package and writes /opt/tuladb/node.toml, validates it, checks the ports and probes the disks. It then starts tuladbd under systemd and waits until the node reports ready. It also generates an admin API key; anonymous clients can read but not write.

KEY="$(sudo cat /root/.tuladb/admin.key)"

On a Mac, run the macOS installer without sudo. It installs under ~/.tuladb and prints the command that starts the node; the key is ~/.tuladb/secrets/admin.key, and tulactl is ~/.tuladb/tulactl (not on your PATH). Install TulaDB describes every step, and a three-node cluster.

2. Create a ledger and two accounts

L="--ledger 10 --currency 840"
tulactl --api-key "$KEY" ledger-create $L --yes
tulactl --api-key "$KEY" create-account --id 1001 $L --limit-low -1000000
tulactl --api-key "$KEY" create-account --id 1002 $L

Account 1001 may go negative, down to its lower limit, so it can fund the other.

3. First transfer

tulactl --api-key "$KEY" transfer --from 1001 --to 1002 --amount 25 $L --txn quickstart-1
  ✓ OK   phase: POSTED
    batch_seq: 10
    transfer_id: Qp7XJkZd6JE3SgOPxCXiu1U3vz2kKsZPDOi
    debit  account — posted:          -2500   available:          -2500
    credit account — posted:           2500   available:           2500

--amount is decimal, in the currency’s major unit: 25 is 25.00 USD. Balances print in minor units (cents), so 2500; balance --scaled prints them as decimals. A value with more decimals than the currency allows is refused, never rounded. transfer_id is the transfer’s permanent identifier, and batch_seq its position in the replicated log.

4. Try to double-post

Run exactly the same command again:

  ↺ OK_DUPLICATE   phase: POSTED
    batch_seq: 10
    transfer_id: Qp7XJkZd6JE3SgOPxCXiu1U3vz2kKsZPDOi

The engine recognised the operation identity (source_id, ledger_id, currency, txn_id) and answered with the original result: the same transfer_id, at the same position. Nothing was applied a second time. That is the idempotency contract. A client timeout, a redelivered message or a crashed worker rerunning its batch can retry safely, because duplicate detection is durable in the engine, not a cache in your application. Read more in Idempotency.

5. Read it back

tulactl --api-key "$KEY" balance --id 1002 $L
tulactl --api-key "$KEY" get --source 1 --ledger 10 --txn quickstart-1 --currency 840
  Account 1002:

  posted balance:                2500
  available balance:             2500
  credits posted:                2500
  debits posted:                    0

The balance is 25.00 after two submissions. Balances have posted, pending and available components: holds are visible state, never a hidden flag (see Holds). get fetches the durable record by the identity you chose; get --transfer-id fetches it by the engine’s.

6. Check the node, then tear down

sudo ./tuladb-installer-0.0.1-preview-linux-x86_64 status

status reports the service, process health, the build and the readiness verdict on separate lines. It exits 0 when the node is ready, 3 when nothing is installed, 4 when tuladbd does not answer and 5 when it answers but is not ready, so a script can wait on it.

sudo ./tuladb-installer-0.0.1-preview-linux-x86_64 uninstall                                   # keeps the data
sudo ./tuladb-installer-0.0.1-preview-linux-x86_64 uninstall --purge --yes-delete-financial-data  # deletes it

A purge deletes only the directories this installer created; see Uninstall.

Where next