Skip to content

README.md

Latest commit

 

History

History
201 lines (144 loc) · 5.11 KB

README.md

File metadata and controls

201 lines (144 loc) · 5.11 KB
Raw

@invoice-liquidity/cli

Command-line interface for common Invoice Liquidity Network contract operations on Stellar.

By participating in this project, you agree to abide by our Code of Conduct.

Table of Contents

Install

npm install -g @invoice-liquidity/cli

This publishes the iln binary.

Configuration

Create a .iln.json file in your working directory:

{
  "network": "testnet",
  "contractId": "CD3TE3IAHM737P236XZL2OYU275ZKD6MN7YH7PYYAXYIGEH55OPEWYJC",
  "tokenId": "CDUMMYYOURTOKENIDHERE",
  "keypairPath": "~/.config/iln/freelancer.secret"
}

Supported keys:

  • network: testnet, mainnet, or standalone
  • contractId: ILN contract ID
  • tokenId: default token contract to use for submit
  • keypairPath: path to a file containing a Stellar secret key
  • rpcUrl: optional RPC override
  • networkPassphrase: optional passphrase override

Environment fallbacks:

  • ILN_NETWORK
  • ILN_CONTRACT_ID
  • ILN_TOKEN_ID
  • ILN_KEYPAIR_PATH
  • ILN_RPC_URL
  • ILN_NETWORK_PASSPHRASE

Commands

Local Development Environment

iln dev start
iln dev status
iln dev stop
iln dev reset
  • start launches the local Stellar quickstart Docker container, registers the local network, creates/funds development keys, deploys a built ILN WASM when available, and writes .env.local.
  • stop removes the local quickstart container.
  • reset removes local generated state and starts fresh.
  • status prints node, RPC, contract, and token state.

Requires Docker to be installed and running. Contract deployment also requires the Stellar CLI and a built contract WASM.

Submit

iln submit --payer G... --amount 100 --due 2025-12-31 --rate 300
  • --amount uses display units and is converted to Stellar stroops internally.
  • --due accepts either YYYY-MM-DD or a Unix timestamp.
  • --token can override the configured tokenId if needed.

Fund

iln fund --id 1

By default this funds the remaining balance on the invoice. To partially fund:

iln fund --id 1 --amount 25

Pay

iln pay --id 1

Status

iln status --id 1

List

iln list --address G...

This lists invoices where the address is the freelancer, payer, or recorded funder.

Development - Testnet Account Seeder

iln dev seed

Creates and funds 3 development accounts (freelancer, payer, liquidity_provider) on testnet with USDC/EURC trustlines configured. Fully idempotent - running multiple times reuses existing accounts.

Output:

  • Generates keypairs for 3 accounts
  • Funds each via Friendbot with XLM
  • Sets up USDC and EURC trustlines
  • Saves account details to .env.testnet.accounts (gitignored)

Requires: Active internet connection and testnet network configuration.

For detailed setup instructions, see SEEDER.md.

Local integration testing

The integration suite is designed for the repository's standalone Soroban environment.

  1. Start the local network:
docker-compose up -d

  1. Deploy and seed the contract.

  2. Export the local fixture values:

export ILN_CLI_LOCAL_CONTRACT_ID=...
export ILN_CLI_LOCAL_TOKEN_ID=...
export ILN_CLI_LOCAL_FREELANCER_SECRET=...
export ILN_CLI_LOCAL_FREELANCER_PUBLIC_KEY=...
export ILN_CLI_LOCAL_PAYER_SECRET=...
export ILN_CLI_LOCAL_PAYER_PUBLIC_KEY=...
export ILN_CLI_LOCAL_FUNDER_SECRET=...
  1. Run the integration suite:
cd cli
npm run test:integration

Scripting and Command Chaining

The CLI supports advanced automation, piping, and command chaining through standard Unix behaviors:

1. JSON Output Formatting

Pass the global --json option to receive structured, machine-parseable JSON responses from all retrieval and submission/mutation commands.

iln status --id 42 --json

2. Standard Input (Stdin) Piping

If a command (like fund, pay, or status) is executed without the --id option in a non-interactive shell, it automatically attempts to parse standard input. Stdin can be passed either as a raw string ID or as a JSON object containing invoiceId or id (matching the output generated by the --json option).

This enables seamless pipeline chaining:

# Submit an invoice and fund it immediately in a single chain:
iln submit --payer GABC... --amount 100 --due 2026-12-31 --rate 300 --json | iln fund --yes --json

3. Exit Codes

All commands return appropriate shell exit codes for error handling in scripts:

  • 0: Command completed successfully.
  • 1: Command execution or transaction submission failed.

In JSON mode, if an error is thrown, a JSON error representation is written to stdout:

{
  "success": false,
  "error": "Error details..."
}