docs: fix #294 add sdk usage tutorial covering importer lifecycle

[fhayvy]

Closes #294

PR Description

This Pull Request creates a comprehensive, step-by-step developer tutorial in sdk-tutorial.md that walks through the entire importer lifecycle using the TariffShield SDK.

While the SDK README provides a standard API reference, developers require a narrative walkthrough to understand how the SDK methods are sequenced to complete a real-world business flow. This tutorial guides developers through:

1. Prerequisites: Aligning local development environments (Node.js 20+, Stellar Testnet account, contract deployment, and the Express API).
2. Step 1: Installation & Client Instantiation: Setting up @tariff-shield/sdk and @stellar/stellar-sdk, and instantiating the TariffShieldClient with the correct network passphrase and RPC URL.
3. Step 2: Importer Registration: Registering a new importer on-chain using registerImporter, explaining how this updates the contract's ledger state and how the off-chain API synchronizes this with the Postgres database.
4. Step 3: Depositing Collateral: Depositing locked collateral via depositCollateral, detailing the transaction simulation, fee payment, and signing flow, and verifying transactions on Stellar Expert.
5. Step 4: Depositing Reserve: Depositing funds into the auto-top-up pool via depositReserve, highlighting the functional differences between the locked collateral and yield-bearing reserve buckets.
6. Step 5: Simulated Tariff Spike & Auto-Top-Up: Simulating a tariff spike by hitting the API's /importers/:id/upload-tariff-csv endpoint, followed by triggering the permissionless autoTopUp method to automatically rebalance the accounts, and querying the updated state using getAccount.
7. Step 6: Yield Accrual: Triggering simulated yield accrual using accrueYield as a surety admin, and explaining the off-chain APY-based calculation formula.

Changed

• Documentation (docs/sdk-tutorial.md) [NEW]:
  • Created sdk-tutorial.md containing the complete importer lifecycle guide with fully commented, type-safe TypeScript snippets.
  • Added detailed explanations of on-chain state transitions and database records for each stage.
  • Documented the APY yield rate calculation formula referenced in the project architecture.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tariff-shield-web	Error		Jun 30, 2026 1:45am

[vercel]

Deployment failed with the following error:

The `vercel.json` schema validation failed with the following message: should NOT have additional property `rootDirectory`

Learn More: https://vercel.com/docs/concepts/projects/project-configuration

[drips-wave]

@fhayvy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits