docs: add secrets management guide

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.

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.

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.

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.