@spield/sdk 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.4.0
+
+Breaking. The SDK now targets only the SR-based (v2) contracts on Testnet.
+
+- Remove the legacy v1 protocol: the `wrapper`, `vault`, `market`, `tokens`, `portfolio` and
+  `protocol` clients, their config addresses, and the PT+YT dual-trustline path. YT is a contract
+  token issued by the yield engine and never needed a trustline.
+- Promote the protocol namespaces to the client itself: `client.sr`, `client.yield`, `client.market`
+  and friends replace `client.current.*` / `client.v2.*`, which are gone along with `SpieldV2Client`.
+- Flatten the network config: the former `v2.contracts` / `v2.assets` are now `contracts` / `assets`,
+  so `SpieldV2NetworkConfig` and the `requireV2` guard are no longer needed.
+- Remove `mainnetPreview()`. The SDK ships Testnet only; use `customNetwork()` for anything else.
+- Map contract errors from `contracts/shared/src/errors.rs` instead of guessing from message text.
+  A failed `sr.deposit` previously reported "The wallet needs PT and YT trustlines before receiving
+  minted tokens", which was both v1-shaped and wrong for a USDC wrap; `Error(Contract, #N)` codes
+  such as the deposit cap (#107), slippage floors (#105) and dust (#106) were not surfaced at all.
+- Move `fromScalar12` to `./sr` alongside `SCALAR_12`; it is still exported from the package root.
+- Cover the USDC → SR → PT + YT path in the integration suite, asserting the exact contract,
+  method and argument layout of `sr.deposit` and `yield.mint_py`.
+- Update the six examples and the browser test app to the flat client.
+
+## Unreleased
+
+- Point the v2 Testnet config at the 2026-08-27 SR redeploy. The SDK was still pinned to the
+  superseded stack recorded in `deploy_sr_testnet.state.pre-redeploy-20260827`, whose deposit cap is
+  full (zero headroom), so wraps and deposits could not succeed. SR, strategy, yield engine, market,
+  vault, router and the PT SAC all move, and the PT trustline asset becomes `SPLDPT6`.
+- Assert the SR deposit-cap invariant in the Testnet read smoke instead of pinning a live headroom
+  value that changes with every deposit.
+- Fix a packaging defect that made the tarball uninstallable under npm: `@spield/sdk` declared
+  itself as a `link:` dependency on a machine-local path, so `npm install` failed with
+  `EUNSUPPORTEDPROTOCOL`.
+- Drop the unused `dotenv` runtime dependency, so consumers only pull in `@stellar/stellar-sdk`.
+- Fill in the unset `allowBuilds` placeholder in `pnpm-workspace.yaml`; `pnpm install` exited 1 with
+  `ERR_PNPM_IGNORED_BUILDS` on a fresh clone.
+- Stop type-checking `examples/sdk-test-app` from the root `tsconfig.json`; its browser wallet
+  dependencies are not part of the root install, so `pnpm run typecheck` exited 2. The demo is still
+  type-checked by its own `pnpm --dir examples/sdk-test-app run build`.
+- Drop the unfulfilled `MIT` license declaration and its `files` entry; the package ships no
+  license for now.
+
+## 0.3.1
+
+- Track the Testnet SR deposit-cap rollout with `SrState.depositCapReached`, while preserving the
+  existing typed cap and headroom amounts.
+- Verify the live 100 USDC cap and zero headroom without treating the cap as a withdrawal pause.
+
+## 0.3.0
+
+- Integrate the 2026-08-27 contract-source changes: Blend strategy reads, holder/LP/receipt
+  keep-alives, caller-controlled LP `minShares`, resumable vault redemption state, and vault surplus.
+- Detect the deployed old market ABI for zero-bound liquidity adds and normalize old vault
+  receipts/stats so the latest SDK continues to work before the Testnet contracts are upgraded.
+- Track the latest router deployment from `deploy_sr_testnet.state`.
+
+## 0.2.0
+
+- Add the current SR-based protocol under `client.current` / `client.v2`.
+- Ship the live 2026-08-25 Testnet SR, yield-engine, PT/SR market, vault, router, PT, and USDC addresses.
+- Add live-safe YT buy/sell orchestration, SR partial exits, v2 health/portfolio reads, and PT-only trustline setup.
+- Keep the original v1 top-level clients for backward compatibility.
+
+## 0.1.0
+
+- Initial SDK scaffold for Spield Testnet fixed-rate vault, wrapper, market, tokens, portfolio, and protocol APIs.

package/README.md

@@ -0,0 +1,94 @@
+# @spield/sdk
+
+TypeScript SDK for the Spield Protocol on Stellar Testnet. The SDK targets the SR-based contracts
+recorded in `deploy_sr_testnet.state` (2026-08-27 redeploy).
+
+```ts
+import { FreighterSigner, SpieldClient, testnet } from '@spield/sdk';
+
+const client = new SpieldClient({
+  network: testnet(),
+  signer: new FreighterSigner(),
+});
+
+const health = await client.protocol.getHealth();
+const srQuote = await client.sr.previewDeposit({ amount: '100' });
+const ptQuote = await client.router.quoteBuyPt({ usdcIn: '100' });
+
+await client.tokens.ensurePtTrustline();
+await client.router.buyPt({ usdcIn: '100' });
+```
+
+## The protocol model
+
+USDC wraps into **SR**, a yield-bearing share token over a Blend strategy. SR splits into **PT**
+(principal) and **YT** (yield). PT trades against SR on the market, and the fixed-rate vault sells a
+guaranteed coupon out of its PT inventory.
+
+```
+USDC ──sr.deposit──▶ SR ──yield.mintPy──▶ PT + YT
+                     ▲                     │
+                     └──yield.redeemPy─────┘
+```
+
+SR is a share token, so **one SR is not one USDC** — use `sr.previewDeposit` / `sr.previewRedeem`, or
+`sr.srToUnderlying` / `sr.underlyingToSr` with the current `exchangeRate`.
+
+## Namespaces
+
+| Namespace | What it does |
+|---|---|
+| `client.sr` | Wrap USDC into SR shares; unwrap fully or partially |
+| `client.strategy` | Blend rate guard, position value, withdrawable liquidity |
+| `client.yield` | Mint/redeem PT + YT, read and claim interest, transfer YT |
+| `client.market` | PT/SR quotes, PT and YT trades, liquidity |
+| `client.vault` | Fixed-rate quotes, receipts, deposit, redeem, harvest |
+| `client.router` | One-transaction USDC routes for PT, redemption, and yield claims |
+| `client.tokens` | USDC/SR/PT/YT balances and the single required PT trustline |
+| `client.portfolio` | Wallet-wide balances, interest, LP position, vault receipts |
+| `client.protocol` | Cross-contract health and yield-engine solvency |
+
+**Trustlines:** PT is the only classic asset, so it is the only trustline a wallet needs. The yield
+engine contract *is* the YT token — YT is a contract token with no trustline. Call
+`client.tokens.ensurePtTrustline()` once before receiving PT.
+
+**YT trades take two signatures.** The deployed Blend-backed stack cannot fit a YT wrap+trade or
+trade+unwrap into a single Soroban transaction. `client.buyYtFromUsdc()` and
+`client.sellYtToUsdc()` deliberately use up to two wallet signatures and report progress.
+
+See [USAGE.md](./USAGE.md) for complete examples.
+
+## Scope
+
+Testnet only. There is no mainnet configuration in this SDK. Point it at another deployment with
+`customNetwork()` if you need one.
+
+## Development and verification
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run test:package
+pnpm run test:e2e:testnet
+```
+
+The Testnet read suite validates SR, Blend liquidity, yield-engine solvency, PT/SR reserves and
+prices, vault backing, and router quotes against the checked-in live deployment, and cross-checks
+that the engine, market and vault all agree on one series expiry. The write smoke test is skipped
+unless a disposable funded `SPIELD_E2E_SECRET` is provided; it only creates/verifies the PT
+trustline.
+
+## Manual SDK test app
+
+A browser console that exercises every SDK method against Testnet:
+
+```bash
+pnpm --dir examples/sdk-test-app install
+pnpm demo
+```
+
+Reads work without a wallet. Writing uses the same multi-wallet connector as the Protocol frontend
+and requires a disposable funded Testnet account.
+See [the demo README](./examples/sdk-test-app/README.md) for details.

package/RELEASE.md

@@ -0,0 +1,8 @@
+# Release
+
+1. Run `pnpm test`.
+2. Run `pnpm build`.
+3. Run `npm pack --dry-run`.
+4. Publish with `npm publish --access public`.
+
+Each release should mention the Spield deployment/config it targets.

package/USAGE.md

@@ -0,0 +1,215 @@
+# Using the Spield SDK
+
+## Create a client
+
+```ts
+import { FreighterSigner, SpieldClient, testnet } from '@spield/sdk';
+
+// Omit the signer for read-only use.
+const client = new SpieldClient({
+  network: testnet(),
+  signer: new FreighterSigner(),
+});
+
+// Protocol namespaces live directly on the client: client.sr, client.yield, client.market, ...
+```
+
+`testnet()` contains the verified SR deployment from the 2026-08-27 redeploy, and is the default
+when no `network` is given. The SDK ships Testnet only — use `customNetwork()` to point it at any
+other deployment.
+
+## Amounts
+
+Strings and numbers are human token amounts. A `bigint` is already in base units.
+
+```ts
+import { fromBaseUnits, toBaseUnits } from '@spield/sdk';
+
+toBaseUnits('10.25');       // 102500000n
+fromBaseUnits(102500000n);  // "10.25"
+
+const quote = await client.vault.quoteFixedRate({ amount: '100' });
+console.log(quote.payout.formatted, quote.payout.raw);
+```
+
+All protocol tokens use seven decimals. Prices, APYs, and exchange-rate indexes use 12-decimal
+fixed point and are returned as exact `bigint` values plus display-friendly fields where useful.
+
+## PT trustline
+
+Only PT requires a trustline. The yield engine itself is the YT token, so creating a YT trustline
+is incorrect.
+
+```ts
+const status = await client.tokens.getPtTrustline({ owner: walletAddress });
+if (!status.ready) await client.tokens.ensurePtTrustline();
+```
+
+Set this up before any flow that delivers PT: buying PT, minting PT+YT, or removing liquidity.
+
+## SR: wrap and unwrap
+
+SR represents shares in the Blend-backed strategy. Its USDC value is `shares × exchangeRate / 1e12`.
+
+```ts
+const preview = await client.sr.previewDeposit({ amount: '50' });
+await client.sr.deposit({ amount: '50', minSharesOut: preview.raw * 99n / 100n });
+
+const state = await client.sr.getState();
+const balance = await client.sr.getBalance({ owner: walletAddress });
+const value = client.sr.srToUnderlying(balance.raw, state.exchangeRate);
+
+await client.sr.redeem({ shares: balance.raw, minUnderlyingOut: 0n });
+```
+
+During a Blend liquidity crunch, query `getState().maxRedeemable` and use `redeemPartial()` so the
+available portion can exit while the rest remains held.
+
+`getState()` also reports `depositCap`, `depositHeadroom`, and `depositCapReached`. A reached cap
+blocks new deposits only; it does not block `redeem()` or `redeemPartial()`. The live Testnet cap is
+currently 100 USDC and is below its existing TVL, so `depositCapReached` is expected to be `true`.
+
+## PT and YT engine
+
+```ts
+await client.tokens.ensurePtTrustline();
+await client.yield.mintPy({ srIn: '50' });
+
+const interest = await client.yield.getClaimableInterest({ owner: walletAddress });
+await client.yield.claimYield();
+
+await client.yield.transferYt({ to: receiver, amount: '5' });
+await client.yield.redeemPy({ amount: '10' });
+```
+
+Before expiry, `redeemPy()` burns both PT and YT. After expiry, it burns PT only and redeems
+principal at face value.
+
+## Buy and sell PT with USDC
+
+The router wraps/unwraps SR inside supported routes and applies a 1% output floor by default.
+
+```ts
+await client.tokens.ensurePtTrustline();
+
+const buyQuote = await client.router.quoteBuyPt({ usdcIn: '100' });
+await client.router.buyPt({ usdcIn: '100', slippageBps: 100 });
+
+const sellQuote = await client.router.quoteSellPt({ ptIn: '25' });
+await client.router.sellPt({ ptIn: '25', slippageBps: 100 });
+```
+
+Pass an explicit `minPtOut` or `minUsdcOut` to replace the quote-derived floor. Zero is valid when
+the caller intentionally disables the floor.
+
+## Buy and sell YT with USDC
+
+Use the high-level two-step methods. Against the deployed Blend pool, the combined router YT paths
+exceed Soroban's transaction resource budget even though each leg succeeds separately.
+
+```ts
+await client.buyYtFromUsdc({
+  ytOut: '100',
+  onProgress: (step, index, total) => console.log(step, `${index}/${total}`),
+});
+
+await client.sellYtToUsdc({
+  ytIn: '50',
+  onProgress: (step, index, total) => console.log(step, `${index}/${total}`),
+});
+```
+
+`buyYtFromUsdc()` checks the wallet's SR balance, wraps only the shortfall, pads `max_sr_in` by 3%
+to keep authorization stable across index drift, and then buys exact YT output. Excess SR is
+refunded by the market. `sellYtToUsdc()` sells YT, reads the actual SR received, and unwraps it.
+
+For wallets that already hold SR, use direct market routes:
+
+```ts
+const quote = await client.market.quoteBuyYt({ ytOut: '100' });
+await client.market.buyYt({ ytOut: '100' });
+await client.market.sellYt({ ytIn: '25', minSrOut: 0n });
+```
+
+## Fixed-rate vault
+
+```ts
+const quote = await client.vault.quoteFixedRate({ amount: '100' });
+const deposit = await client.vault.deposit({ amount: '100' });
+
+const stats = await client.vault.getStats();
+const receipts = await client.vault.getOwnerReceipts({ owner: walletAddress });
+const remaining = receipts[0]
+  ? await client.vault.getRedeemRemaining({ receiptId: receipts[0].receiptId })
+  : null;
+
+if (receipts[0]?.open && Date.now() >= receipts[0].maturityDate.getTime()) {
+  await client.vault.redeemReceipt({ receiptId: receipts[0].receiptId });
+}
+
+await client.vault.harvest();
+```
+
+The vault quote and receipt payout are USDC-denominated. On the latest contract ABI, redemption is
+resumable: a liquidity-constrained call banks progress in `receipt.collected`, while
+`getRedeemRemaining()` reports what is still owed. The SDK derives the same value from old receipts
+when connected to the currently deployed pre-upgrade Testnet vault.
+
+## Market, portfolio, and health
+
+```ts
+const stats = await client.market.getStats();
+const lp = await client.market.getLpPosition({ owner: walletAddress });
+
+await client.market.addLiquidity({ ptIn: '10', srIn: '10', minShares: '9.9' });
+await client.market.removeLiquidity({ shares: lp.shares.raw, minPtOut: 0n, minSrOut: 0n });
+
+const portfolio = await client.portfolio.getPortfolio({ owner: walletAddress });
+const health = await client.protocol.getHealth();
+const solvency = await client.protocol.getSolvency();
+```
+
+Raw market routes use SR, not USDC. Quote methods return `available: false` when the on-chain quote
+is zero; this means the pool cannot fill the requested size.
+
+`minShares` is supported by the latest market ABI. The SDK detects the currently deployed older
+market and uses its three-argument liquidity call when `minShares` is zero. A positive bound on an
+old deployment fails before wallet signing with `SpieldConfigurationError`.
+
+## Contract ABI compatibility
+
+The SDK includes the latest source-contract additions: SR/YT/LP/receipt keep-alives, caller-bounded
+LP minting, Blend liquidity state, resumable vault receipt fields, remaining redemption reads, and
+vault surplus reads. As verified on 2026-08-27, the public Testnet SR/market/vault addresses still
+carry the preceding ABI. Read mappings and default liquidity adds remain backward-compatible; new
+write entry points become usable when those contracts are upgraded on chain.
+
+## Custom deployments
+
+Supply the full contract set:
+
+```ts
+const network = customNetwork({
+  key: 'custom',
+  networkName: 'TESTNET',
+  networkPassphrase: 'Test SDF Network ; September 2015',
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  horizonUrl: 'https://horizon-testnet.stellar.org',
+  explorerUrl: 'https://stellar.expert/explorer/testnet',
+  decimals: 7,
+  contracts: {
+    sr: '...', strategy: '...', yieldEngine: '...', market: '...',
+    vault: '...', router: '...', pt: '...', usdc: '...',
+  },
+  assets: { pt: { code: '...', issuer: '...' } },
+});
+```
+
+## Errors
+
+The SDK exports `SpieldValidationError`, `SpieldSignerError`, `SpieldContractError`,
+`SpieldRpcError`, and `SpieldConfigurationError`. Write calls simulate before signing, submit only
+after wallet approval, and return `{ hash, status: 'success', explorerUrl }` after confirmation.
+The SDK polls Testnet RPC for up to two minutes by default because an accepted transaction can be
+indexed after ledger close. Override `confirmationTimeoutMs` and `confirmationPollIntervalMs` in
+`SpieldClient` options when your application needs different confirmation behavior.