Skip to content

README.md

Latest commit

 

History

History
254 lines (186 loc) · 7.36 KB

README.md

File metadata and controls

254 lines (186 loc) · 7.36 KB
Raw

Developer Tools

Comprehensive set of tools and utilities for working with the StellopayCore contract.

Table of Contents

  1. CLI Tools
  2. Monitoring and Debugging Tools
  3. Testing Utilities
  4. Code Generation
  5. Development Scripts

CLI Tools

StellopayCore CLI

A command-line interface for managing payroll operations.

Installation

# Install from source
git clone https://github.com/stellopay/stellopay-core
cd stellopay-core/tools/cli
cargo install --path .

# Or install from registry
cargo install stellopay-cli

Real Commands

The CLI exposes five top-level commands. Run stellopay-cli <COMMAND> --help for per-command flags.

Command Description
deploy Deploy a new contract
info Get contract information
status Show CLI status
emergency-withdraw Emergency withdrawal of tokens
webhook Webhook management (see subcommands below)
deploy
stellopay-cli deploy --network testnet --owner <OWNER_ADDRESS>
stellopay-cli deploy --network testnet --owner <OWNER_ADDRESS> --wasm ./target/release/contract.wasm
Flag Required Description
--network No (default: testnet) Network to deploy to
--owner Yes Owner address
--wasm No WASM file path
info
stellopay-cli info --contract-id <CONTRACT_ID>
Flag Required Description
--contract-id No Contract ID to inspect
status
stellopay-cli status

No flags. Displays current CLI configuration status.

emergency-withdraw
stellopay-cli emergency-withdraw --contract-id <CONTRACT_ID> --token <TOKEN_ADDRESS> --recipient <ADDRESS> --amount <AMOUNT>
Flag Required Description
--contract-id No Contract ID
--token Yes Token address
--recipient Yes Recipient address
--amount Yes Amount to withdraw (i128)
webhook

Webhook subcommands manage event subscriptions:

stellopay-cli webhook register --name <NAME> --description <DESC> --url <URL> --events <EVENTS> --secret <SECRET>
stellopay-cli webhook update --webhook-id <ID> [--name <NAME>] [--url <URL>] ...
stellopay-cli webhook delete --webhook-id <ID>
stellopay-cli webhook list --owner <ADDRESS>
stellopay-cli webhook get --webhook-id <ID>
stellopay-cli webhook stats
stellopay-cli webhook test --webhook-id <ID> --event-type <TYPE>
Subcommand Description
register Register a new webhook
update Update an existing webhook
delete Delete a webhook
list List webhooks for an owner
get Get webhook information
stats Get webhook statistics
test Test webhook delivery
Read vs. write: query and invoke

webhook list, webhook get, and webhook stats are read-only — they call SorobanHttpClient::query (defined in tools/cli/src/utils.rs) instead of SorobanHttpClient::invoke. The two methods are intentionally distinct:

query invoke
Purpose Read-only contract simulation Submits a transaction
Requires a signer/secret key No Yes
Mutates on-chain state No Yes
Used by webhook list, webhook get, webhook stats webhook register/update/delete/test, emergency-withdraw

query posts the contract id, method, and arguments to the RPC's /query endpoint with read_only: true and never accepts or forwards a signer. It returns a serde_json::Value (the result field of the RPC response, or the full response body if no result field is present), and surfaces both transport-level failures (non-2xx HTTP status) and RPC-level failures (an error field in the response body) as Err. See the /// doc comment on SorobanHttpClient::query for the exact contract.

Tests for this path live in tools/cli/tests/integration_tests.rs (the test_query_* tests) and run against a local mock RPC server via wiremock, covering: a successful result, an empty result, a response with no result field, an RPC-level error field, a non-2xx HTTP status, a malformed (non-JSON) body, and a check that the outgoing request never carries a signer field.

Configuration

# ~/.stellopay/config.toml
[network]
rpc_url = "https://soroban-testnet.stellar.org:443"
network_passphrase = "Test SDF Network ; September 2015"

[contract]
default_contract_id = "CONTRACT_ID_HERE"

[auth]
secret_key = "SECRET_KEY_HERE"
# Or use environment variable: STELLOPAY_SECRET_KEY

[defaults]
token = "TOKEN_ADDRESS_HERE"
frequency = "monthly"

Keeping Docs in Sync

The authoritative source for available commands is the Commands enum in tools/cli/src/lib.rs. To regenerate this reference after changing the CLI definition:

cargo run -p stellopay-cli -- --help
cargo run -p stellopay-cli webhook --help

Phantom Commands (Not Implemented)

The following commands documented in earlier versions of this file do not exist in the current CLI:

  • payroll create / update / delete / list
  • deposit, pay, bulk-pay
  • contract deploy / initialize / pause / unpause / transfer-ownership
  • token add / remove / list
  • payment process / process-all / schedule / history
  • report payroll / payments / balances
  • analyze events / report
  • debug transaction / trace / state / gas
  • test setup / deploy / accounts / generate / run / report
  • load-test, stress-test, benchmark
  • generate bindings / client / docs / openapi / contract-docs
  • health, stream, export, monitor

These are aspirational features not yet implemented. If you need them, please open a feature request.

Monitoring and Debugging Tools

For real-time event monitoring, query the contract via the Soroban RPC or a block explorer:

stellar contract id --id <CONTRACT_ID>

The CLI does not ship built-in analyze, stream, debug, or monitor subcommands.

Testing Utilities

Test Environment Setup

# Run unit tests
cargo test

# Run integration tests
cargo test --test integration_tests

# Run end-to-end tests (if configured)
npm test -- --testPathPattern=e2e

Existing test scripts are available at scripts/test.sh.

Code Generation

Contract bindings can be generated using the Soroban CLI directly:

# Generate TypeScript bindings (requires soroban-cli)
soroban contract bindings typescript --contract-id <CONTRACT_ID> --output-dir ./src/bindings

The CLI does not ship a built-in generate subcommand.

Development Scripts

Build, test, and monitoring scripts are available in the scripts/ directory as shell scripts with descriptive comments.

Getting Started

  1. Install CLI Tools:

    cargo install stellopay-cli

  2. Set up Development Environment:

    git clone https://github.com/stellopay/stellopay-core
cd stellopay-core

  3. Deploy Test Contract:

    stellopay-cli deploy --network testnet --owner <OWNER_ADDRESS>

  4. Run Tests:

    cargo test

For detailed usage instructions, see the Integration Guide.

Accuracy note: This document was reconciled against the Commands enum in tools/cli/src/lib.rs. If the CLI gains new subcommands, update this file to match. Run cargo run -p stellopay-cli -- --help to verify.