Open once.
Pay per call.

PATH 1 / LOCAL DEMO · NO WALLET

Try the flow without setup.

Install the current Ghostline v0.4.0 release, then run one command. It exercises the local HTTP 402 quote, real voucher signing and verification, and the paid-call flow. It does not connect to a wallet, use test funds, or create a blockchain transaction. To inspect finalized Esmeralda transactions, see the recorded runs.

ghostline demo

For an install-free version, use the browser simulation. For a real testnet run, choose the guided path below; it requires wallet setup and test tTARI.

PATH 2 / GUIDED LIVE ESMERALDA RUN

Let the runner guide you.

The script checks the documented deployment profile, creates fresh local keys, starts the sample API on loopback, makes paid calls, and offers separate confirmations before channel open and settlement. Review both fee dry-runs; the open cap may not be refunded in full.

curl -fsSLo ghostline-esmeralda-demo.sh https://raw.githubusercontent.com/AduAkorful/ghostline/main/scripts/ghostline-esmeralda-demo.sh
less ghostline-esmeralda-demo.sh
bash ghostline-esmeralda-demo.sh

The defaults are 3 calls at 10 µT each with a 100,000 µT deposit. The run is real testnet activity and requires two confirmations. It keeps an owner-only state directory containing the channel mask and service call ledger; remove it only after saving the explorer links and when you no longer need the local record.

PATH 3 / OPTIONAL MANUAL ROUTE

Configure each CLI step yourself.

This walkthrough is for people who want to assemble the channel, service, payment, and settlement commands manually. It is an alternative to the guided run above; completing the guided run does not require these steps.

00 / BEFORE YOU START

Gather real deployment terms.

You need a compatible wallet daemon, the deployed Ghostline template, and a service that accepts the channel terms. Nothing here creates a hosted service or shared wallet.

01 / PREPARE

Create private channel state.

Use an owner-only directory. Generate a fresh payer signing key into a private file; use only its public value in channel parameters and pass the file to ghostline sign --secret-file.

umask 077
mkdir -p /secure/path
ghostline keygen --role payer --out /secure/path/payer-channel.json

The key file is owner-only and contains the signing secret and public key. Use its public_hex in channel parameters and pass the file to ghostline sign --secret-file. Generate a different payer key for every channel. Choose a future expiry epoch and a unique 32-byte nonce. Compute the payer root from the exact channel terms, then initialize the channel record using the provider's real values:

ghostline spec \
  --network-tag <esmeralda-network-tag> \
  --deposit 100000 \
  --payer-hex <payer-public-key-hex> \
  --service-hex <service-public-key-hex> \
  --expiry-epoch <future-epoch> \
  --nonce-hex <unique-32-byte-nonce-hex> \
  --template-hex <deployed-template-hash-hex>

100000 means 0.1 tTARI in integer micro-units. Fees are additional. The full channel init command also needs your wallet accounts, indexer, ledger/session paths, and maximum accepted epoch. See the detailed source guide for every setup flag and troubleshooting note.

02 / SERVICE

Start the other side.

Run the reference API locally, or use a compatible provider. The service sets the price and accepted expiry range. Use a fresh authorization key for each channel; its ledger and the payer session must stay in separate private files.

ghostline-paid-api init --ledger /secure/service-ledger.json --session /secure/service-session.json <channel-parameters>
ghostline-paid-api serve --bind 127.0.0.1:8787 --ledger /secure/service-ledger.json --price 10 \
  --service-key-hex <channel-authorization-public-key> \
  --service-output-key-hex <optional-one-time-payout-public-key> <expiry-terms>

ghostline wallet key-create --url http://127.0.0.1:5100 --out /secure/service-channel-key-id.json
ghostline wallet key-create --url http://127.0.0.1:5100 --out /secure/service-payout-key-id.json

The angle-bracket groups above are explanatory placeholders, not CLI flags. --service-output-key-hex is optional. When used, the quote and voucher bind to that payout key while the channel authorization key still authorizes settlement. Both keys are public in the settlement, so this helps reduce reuse links across later spends; it does not unlink the channel and service.

03 / OPEN AND PAY

Review first. Then pay off-chain.

Keep the payer key file and opener wallet's view-only claim key local and separate. Dry-run the channel open, inspect its fee estimate and required funds, then open with a reviewed positive fee cap. After opening, the payer channel file holds the deposit mask and must be protected.

ghostline channel open --file /secure/path/channel.json --dry-run
ghostline channel open --file /secure/path/channel.json --max-fee <reviewed-opening-fee-cap>
ghostline channel status --file /secure/path/channel.json

Once open, pay for ten calls at 10 µT each. The policy budget limits voucher spending, not transaction fees.

ghostline-paid-api call \
  --url http://127.0.0.1:8787/fortune \
  --session /secure/path/session.json \
  --calls 10 \
  --vendor-hex <service-public-key-hex> \
  --budget 100 \
  --max-per-call 10

Each call signs the next cumulative voucher total. Calls do not submit individual transactions to the chain. The service records accepted calls; that record alone is not proof of settlement.

04 / SETTLE AND VERIFY

Submit one aggregate total.

Stop paying on this channel. Dry-run settlement and review the fee before choosing to submit. Choose a --max-fee cap that covers the dry-run requirement; the channel-file command defaults to 100,000 µT.

ghostline channel settle --file /secure/path/channel.json --dry-run --max-fee <reviewed-fee-cap>
# Submit only after reviewing the dry-run:
ghostline channel settle --file /secure/path/channel.json --submit --max-fee <reviewed-fee-cap>

ghostline indexer result --url <esmeralda-indexer-url> --transaction-id <settlement-transaction-id>

Confirm Finalized Commit. The indexer confirms the transaction's finality; the service ledger supplies the call count and accepted amount. Those are separate records, and the amount is hidden in the tested transaction fields.

ALTERNATIVE / REFUND

Refund after expiry.

If the channel remains unspent through expiry, the payer can use the refund branch. This cannot follow a successful settlement. The channel-file refund helper defaults to a 100,000 µT maximum fee; set --max-fee to the cap you reviewed in the dry-run. It needs the payer fee account and payer signing key.

ghostline channel refund --file /secure/path/channel.json --submit --dry-run --max-fee 10000 --seal-key-id-file /secure/path/payer-key-id.json
# Submit only after confirming expiry, output state, and reviewed fee cap:
ghostline channel refund --file /secure/path/channel.json --submit --max-fee 10000 --seal-key-id-file /secure/path/payer-key-id.json

RESEARCH PROTOTYPE / POOLED CLOSE

One transaction for multiple channels.

An experimental SDK path can settle multiple channels into a pooled service output. The Esmeralda prototype finalized a transaction spending two channel inputs and creating three stealth outputs; each channel's local service ledger recorded 20 paid calls.