Skip to content

implementation.md

Latest commit

 

History

History
65 lines (49 loc) · 4.92 KB

implementation.md

File metadata and controls

65 lines (49 loc) · 4.92 KB
Raw

TariffShield Issue Implementations

This document tracks the implementations completed to resolve issues #289, #285, #283, and #288.

1. Issue #289: Mermaid Architecture Diagrams

We added three Mermaid diagrams to ARCHITECTURE.md to describe system topology and key sequence flows.

System Topology Diagram

A top-down (graph TD) layout showing the flow of communication:

  • Browser/Client UI connects to the Next.js Frontend (Vercel) via HTTPS.
  • Next.js Frontend connects to the Express API (Render) via HTTPS / JWT.
  • Express API connects to the PostgreSQL Database (CRM mirror) via SQL.
  • Express API invokes the SDK (TariffShieldClient), which calls the Soroban Contract via Soroban RPC JSON-RPC protocols.
  • A clear line style legend was added at the bottom: solid lines represent synchronous calls, while dashed lines represent asynchronous event emissions and indexing.

Sequence Diagram: Tariff Spike & Auto-Top-Up Flow

A diagram showing how the system acts when a tariff spike occurs:

  • CBP Webhook pushes CSV/estimates to the Express API.
  • Express API saves the tariff_upload to PostgreSQL.
  • Express API calculates and invokes setRequiredCollateral on-chain using the TariffShieldClient SDK.
  • If a collateral shortfall is detected, the Express API invokes autoTopUp on-chain.
  • The TariffShieldContract moves funds from reserve to collateral, emits the topup event, which the Express API captures and mirrors into the contract_events database log.

Sequence Diagram: Surety Admin Clawback Flow

A diagram showing the emergency clawback procedure:

  • The Surety Admin UI requests a clawback action.
  • The Express API performs role-based authorization verification (surety_admin).
  • The API invokes the clawback method on the TariffShieldClient SDK.
  • The SDK calls clawback on TariffShieldContract, draining balances to the surety wallet and freezing the account.
  • The contract emits a clawback event, which is mirrored by the Express API to the database audit logs.
  • A response is returned back to the UI.

2. Issue #285: CI Formatting and Clippy Lints Gate

We created a linting gate for contract Rust code.

  • Format Configuration: Created rustfmt.toml in the repository root to specify strict format limits (max_width = 100 and edition = "2021").
  • CI Integration: Modified .github/workflows/ci.yml to include parallel fmt and clippy jobs. Both jobs utilize the same cargo cache keys as the test job to avoid rebuilding dependencies.
  • Pre-commit Hook Suggestion: Added explicit guidelines on configuring a local git pre-commit hook to automatically check Rust formatting locally in CONTRIBUTING.md.

3. Issue #283: Automated Changelog Generation

We integrated the Conventional Commit standard with automated changelog updates.

  • Dependencies: Added conventional-changelog-cli to devDependencies in package.json.
  • Script: Added a "changelog" script: "conventional-changelog -p angular -i CHANGELOG.md -s".
  • Baseline Changelog: Generated a retroactive, complete history from commit history in CHANGELOG.md using npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0.
  • Readme Reference: Linked the changelog within README.md under the "Changelog" heading.

4. Issue #288: Deployment and Verification Guide

We wrote a detailed step-by-step deploy runbook in docs/deployment.md.

  • Prerequisites: Clearly listed tools and version bounds for Node.js 20, Rust target wasm32, Stellar CLI, Docker, and Render/Vercel platforms.
  • Env Config Reference: Mapped out a table of all environment variables for both API and Web configurations with example values, validation types, and risk levels.
  • Soroban Commands: Documented commands for compiling (cargo build), optimizing (stellar contract optimize), deploying (stellar contract deploy), and initializing (stellar contract invoke) on testnet/mainnet.
  • Render & Vercel: Provided templates for render.yaml service settings, instructions to deploy containerized APIs on Render, and linking/deploying web assets using vercel --prod.
  • Post-Deploy Smoke Tests: Outlined three checks to verify API health (/health), sign up (/auth/signup), and inspect on-chain account state (get_account).
  • Rollback Actions: Outlined rollback steps for Vercel, Render revisions, and multi-sig Soroban contract upgrades via propose_upgrade.