From a9ab5af9b30e4a0114dc0a299dac09084b5af7f2 Mon Sep 17 00:00:00 2001 From: MAGARET Date: Sat, 27 Jun 2026 10:53:20 +0000 Subject: [PATCH 1/4] docs: add monitoring and alerting guide --- deploy/monitoring/alert-rules.yml | 20 +++++ docs/operations/monitoring-and-alerting.md | 100 +++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 deploy/monitoring/alert-rules.yml create mode 100644 docs/operations/monitoring-and-alerting.md diff --git a/deploy/monitoring/alert-rules.yml b/deploy/monitoring/alert-rules.yml new file mode 100644 index 0000000..ccd40eb --- /dev/null +++ b/deploy/monitoring/alert-rules.yml @@ -0,0 +1,20 @@ +groups: + - name: pulsar-contract-alerts + rules: + - alert: HighPaymentErrorRate + expr: rate(payment_errors_total[5m]) / rate(payment_requests_total[5m]) > 0.05 + for: 5m + labels: + severity: critical + annotations: + summary: Payment processing error rate is above threshold + description: Investigate the contract or upstream token integration immediately. + + - alert: HighPaymentLatency + expr: histogram_quantile(0.95, sum by (le) (rate(payment_processing_seconds_bucket[10m]))) > 2 + for: 5m + labels: + severity: warning + annotations: + summary: Payment processing latency is elevated + description: Review recent deployments and contract invocation patterns. diff --git a/docs/operations/monitoring-and-alerting.md b/docs/operations/monitoring-and-alerting.md new file mode 100644 index 0000000..132bf5f --- /dev/null +++ b/docs/operations/monitoring-and-alerting.md @@ -0,0 +1,100 @@ +# Monitoring and Alerting + +This guide defines a practical baseline for monitoring the Pulsar payment-processing stack, including contract health, application performance, infrastructure, and operational alerts. + +## Goals + +- Track contract and application health in real time. +- Detect regressions in payment throughput, error rates, and latency. +- Provide actionable alerts for on-call responders. +- Keep alerting lightweight and compatible with common observability tools. + +## Metrics to collect + +### Application metrics + +- Request volume and success/error rate +- Payment processing latency (p50/p95/p99) +- Refund initiation and execution latency +- Contract invocation failures +- Authentication failures and rejected transactions + +### Infrastructure metrics + +- CPU usage per service/container +- Memory usage and pressure +- Disk usage and inode pressure +- Network I/O and dropped packets + +### Database and storage metrics + +- Connection pool saturation +- Query latency for contract state reads/writes +- Storage growth and compaction backlog + +### Business metrics + +- Payments per hour +- Refunds per hour +- Average payment value +- Failed payment rate +- Merchant registration rate + +## Recommended alert thresholds + +| Signal | Warning | Critical | +| --- | --- | --- | +| Error rate | > 2% for 10m | > 5% for 5m | +| P95 latency | > 800ms for 15m | > 2s for 5m | +| CPU usage | > 75% for 15m | > 90% for 5m | +| Memory usage | > 80% for 15m | > 95% for 5m | +| Disk usage | > 80% for 1h | > 95% for 15m | +| Payment throughput drop | < 80% of baseline for 15m | < 50% of baseline for 5m | + +## Alert routing + +- Primary channel: incident Slack channel +- Secondary channel: email and PagerDuty +- Escalation path: + 1. On-call engineer + 2. Backend lead + 3. Engineering manager + +## On-call rotation + +- Rotate weekly for the initial rollout. +- Keep a primary and secondary on-call contact. +- Document escalation steps in the incident runbook. + +## Example Prometheus-style scrape config + +```yaml +scrape_configs: + - job_name: pulsar-api + static_configs: + - targets: ["api:9100"] + metrics_path: /metrics + scrape_interval: 15s +``` + +## Example alert rules + +```yaml +groups: + - name: pulsar-alerts + rules: + - alert: HighErrorRate + expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05 + for: 5m + labels: + severity: critical + annotations: + summary: Elevated request error rate +``` + +## Operational checklist + +- Verify dashboards are populated after deployment. +- Test each alert pathway at least once per quarter. +- Review thresholds after observing baseline behavior. +- Preserve runbooks and dashboard links in the incident channel. From 384af11b8cb44ed83117c9428f44ef672acd6ebb Mon Sep 17 00:00:00 2001 From: MAGARET Date: Sat, 27 Jun 2026 10:53:38 +0000 Subject: [PATCH 2/4] docs: add smart contract API reference --- docs/smart-contract-api.md | 162 +++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/smart-contract-api.md diff --git a/docs/smart-contract-api.md b/docs/smart-contract-api.md new file mode 100644 index 0000000..867ef70 --- /dev/null +++ b/docs/smart-contract-api.md @@ -0,0 +1,162 @@ +# Smart Contract API Reference + +This document summarizes the public API surface of the payment-processing contract and the expected behavior of each entry point. + +## Contract overview + +The payment-processing contract exposes functions for merchant onboarding, payment processing, refunds, multisig flows, and data queries. + +## Admin functions + +### `set_admin` + +- Purpose: Initialise the contract administrator. +- Parameters: + - `admin`: the address that will act as the initial admin. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `AdminAlreadySet` if the admin has already been configured. +- Notes: The caller must authenticate. + +### `set_payment_cleanup_period` + +- Purpose: Configure the retention window for expired payments. +- Parameters: + - `admin`: admin address. + - `period`: cleanup period in seconds. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `InvalidInput` for a zero value. + +## Merchant functions + +### `register_merchant` + +- Purpose: Register a merchant for payment processing. +- Parameters: + - `merchant_address`: merchant identity. + - `name`, `description`, `contact_info`: merchant metadata. + - `category`: enum-driven business category. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `MerchantAlreadyRegistered`, `InvalidInput`. + +### `deactivate_merchant` + +- Purpose: Disable a merchant account. +- Parameters: + - `caller`: requester address. + - `merchant_address`: merchant to deactivate. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `Unauthorized`, `MerchantNotFound`. + +## Payment functions + +### `process_payment_with_signature` + +- Purpose: Process a payment after verifying a merchant signature. +- Parameters: + - `payer`: authenticated payer address. + - `order`: payment payload. + - `signature`: 64-byte signature. + - `merchant_public_key`: 32-byte public key. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `InvalidInput`, `PaymentAlreadyExists`, `PaymentExpired`, `MerchantNotFound`, `MerchantInactive`. +- Notes: The contract transfers tokens from the payer to the merchant when validation succeeds. + +### `get_payment_by_id` + +- Purpose: Fetch a payment record for an authorised caller. +- Parameters: + - `caller`: caller address. + - `order_id`: payment identifier. +- Returns: `Result`. +- Errors: + - `PaymentNotFound`, `Unauthorized`. + +## Refund functions + +### `initiate_refund` + +- Purpose: Start a refund request for a completed payment. +- Parameters: + - `caller`: payer or merchant. + - `refund_id`: unique refund id. + - `order_id`: target payment id. + - `amount`: refund amount. + - `reason`: human-readable reason. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `RefundWindowExpired`, `RefundAmountExceedsPayment`, `RefundAlreadyExists`. + +### `approve_refund` + +- Purpose: Approve an initiated refund. +- Parameters: + - `caller`: admin or merchant. + - `refund_id`: refund id. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `RefundNotFound`, `Unauthorized`, `RefundAlreadyApproved`. + +### `execute_refund` + +- Purpose: Finalise an approved refund. +- Parameters: + - `caller`: admin or merchant. + - `refund_id`: refund id. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `RefundNotFound`, `Unauthorized`, `RefundNotApproved`. + +## Multisig functions + +### `initiate_multisig_payment` + +- Purpose: Create a multisig payment request requiring multiple signatures. +- Parameters: + - `caller`: initiator. + - `payment_id`: payment id. + - `order`: payment payload. + - `signers`: addresses required to authorise. + - `threshold`: required number of signatures. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `InvalidInput`, `Unauthorized`, `PaymentAlreadyExists`. + +### `submit_multisig_signature` + +- Purpose: Add a signature to a pending multisig payment. +- Parameters: + - `caller`: signer. + - `payment_id`: pending payment id. + - `signature`: signature bytes. +- Returns: `Result<(), PaymentError>`. +- Errors: + - `InvalidInput`, `PaymentNotFound`, `Unauthorized`. + +## Events + +The contract emits events for major state transitions: + +- `merchant_registered` +- `payment_processed` +- `refund_initiated` +- `refund_approved` +- `refund_executed` +- `multisig_payment_created` + +## Storage and state changes + +- Merchant records are stored by merchant address. +- Payment records are stored by order id. +- Refund records are stored by refund id. +- Global statistics and merchant payment history are updated whenever payments or refunds change. + +## Gas and performance notes + +- Signature verification and token transfer are the most expensive operations. +- Keep payload sizes small and avoid unnecessary storage writes. +- Use the cleanup period and pagination to limit on-chain history growth. From 6333f9a6d5c65bf254f378dfd6537bf1e3a21b6d Mon Sep 17 00:00:00 2001 From: MAGARET Date: Sat, 27 Jun 2026 10:53:54 +0000 Subject: [PATCH 3/4] docs: add developer onboarding guide --- docs/operations/developer-onboarding.md | 76 +++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/operations/developer-onboarding.md diff --git a/docs/operations/developer-onboarding.md b/docs/operations/developer-onboarding.md new file mode 100644 index 0000000..33c28e1 --- /dev/null +++ b/docs/operations/developer-onboarding.md @@ -0,0 +1,76 @@ +# Developer Onboarding Guide + +This guide helps new contributors get productive quickly in the Pulsar contracts repository. + +## Prerequisites + +- Rust stable toolchain +- Stellar CLI +- Docker Desktop or a compatible container runtime +- Git and GitHub access + +## Local setup + +```bash +git clone https://github.com/devEunicee/pulsar-contracts.git +cd pulsar-contracts +rustup toolchain install stable +rustup target add wasm32-unknown-unknown +cargo test --manifest-path contracts/payment-processing-contract/Cargo.toml +``` + +## IDE recommendations + +- VS Code with the Rust Analyzer extension +- Optional: Better TOML and GitHub Pull Requests extensions +- Enable format on save and rust-analyzer diagnostics + +## Pre-commit hooks + +Install the repository hooks before committing: + +```bash +cargo install cargo-fmt +cargo install cargo-clippy +``` + +Then run the formatter and lints before each commit: + +```bash +cargo fmt --all +cargo clippy --all-targets --all-features -- -D warnings +``` + +## Running tests locally + +```bash +cargo test --manifest-path contracts/payment-processing-contract/Cargo.toml +cargo test --manifest-path contracts/payment-processing-contract/Cargo.toml test_successful_payment_with_signature +``` + +## Debugging guide + +- Reproduce the issue with a focused test first. +- Use `RUST_BACKTRACE=1` for panic traces. +- Inspect contract events emitted during tests. +- Read the relevant module files in the contract crate before changing behavior. + +## Common development tasks + +- Add or update contract logic in the contract crate. +- Add or update unit tests in the test modules. +- Update documentation for public API or operational procedures. +- Run formatting and tests before opening a PR. + +## Project structure overview + +- [README.md](../../README.md): high-level project overview and usage instructions. +- [contracts/payment-processing-contract/src](../../contracts/payment-processing-contract/src): contract implementation, storage, error handling, and tests. +- [docs/adr](../adr): architecture decision records. +- [docs/operations](.): operational runbooks and onboarding materials. + +## Troubleshooting + +- If Rust dependencies fail to resolve, update the toolchain and rerun `cargo test`. +- If Stellar CLI commands fail, verify the local network container is running. +- If tests fail unexpectedly, inspect the latest contract changes and the relevant snapshot files. From 1194ee95a16a77c2b2c49a195e97139992305f01 Mon Sep 17 00:00:00 2001 From: MAGARET Date: Sat, 27 Jun 2026 10:54:10 +0000 Subject: [PATCH 4/4] docs: add secrets management guide --- docs/operations/secrets-management.md | 59 +++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/operations/secrets-management.md diff --git a/docs/operations/secrets-management.md b/docs/operations/secrets-management.md new file mode 100644 index 0000000..07e95a6 --- /dev/null +++ b/docs/operations/secrets-management.md @@ -0,0 +1,59 @@ +# Secrets Management + +This document outlines the baseline secret-handling approach for Pulsar deployments and local development. + +## Objectives + +- Centralize credentials, keys, and certificates. +- Reduce the blast radius of compromised credentials. +- Provide auditable access to secrets. +- Support safe rotation and incident response. + +## Recommended tools + +- HashiCorp Vault for centralized secret storage and dynamic credentials. +- AWS Secrets Manager as an alternative for AWS-hosted environments. +- Kubernetes Secrets or an injected sidecar where container orchestration is used. + +## Secret categories + +- API keys and access tokens +- Contract signing keys and admin keys +- Database credentials +- TLS certificates and private keys + +## Access control + +- Enforce least-privilege access by environment and role. +- Restrict secret read access to the services that need them. +- Require MFA for human access to production secrets. +- Keep an audit trail for all secret reads, writes, and rotations. + +## Rotation policy + +- Rotate long-lived credentials at least every 90 days. +- Rotate service account credentials immediately after suspected exposure. +- Maintain a documented rollback procedure for rotated secrets. + +## Injection model + +- Inject secrets at runtime through environment variables or mounted files. +- Avoid baking secrets into container images. +- Prefer short-lived credentials where supported. + +## Development workflow + +- Store local development secrets in a `.env.local` file that is ignored by Git. +- Use a local development vault or an encrypted secrets store for shared test credentials. +- Never commit private keys or certificates to the repository. + +## Encryption at rest + +- Enable encryption for the secrets backend and any backups. +- Protect secret snapshots with separate access controls. + +## Emergency access + +- Maintain a break-glass procedure for production incidents. +- Record who can access emergency credentials and why. +- Review emergency access quarterly.