From 6d21dc39f72803e8a1796caba18cec11ed767b17 Mon Sep 17 00:00:00 2001
From: ZacLou <zaclou@example.com>
Date: Tue, 1 Sep 2026 09:27:32 +0800
Subject: [PATCH] docs: document SorobanRpc -> rpc migration, add min
 stellar-sdk version, warn on SorobanRpc imports

- CONTRIBUTING.md: state @stellar/stellar-sdk >= 12.0.0 peer dependency
- CONTRIBUTING.md: document that new code must use the rpc namespace
- .eslintrc.cjs: add no-restricted-imports warning for SorobanRpc

Closes #612
---
 .eslintrc.cjs   | 13 +++++++++++++
 CONTRIBUTING.md |  6 ++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index a271b4e..1df9a35 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -17,6 +17,19 @@ module.exports = {
       'error',
       { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
     ],
+    // @stellar/stellar-sdk v12 renamed SorobanRpc to rpc. Use rpc for all new code.
+    'no-restricted-imports': [
+      'warn',
+      {
+        paths: [
+          {
+            name: '@stellar/stellar-sdk',
+            importNames: ['SorobanRpc'],
+            message: 'SorobanRpc is deprecated in @stellar/stellar-sdk v12. Import rpc instead.'
+          }
+        ]
+      }
+    ],
   },
   overrides: [
     {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 00ccb8f..ca616fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,6 +32,7 @@ This project follows the [Contributor Covenant Code of Conduct](./CODE_OF_CONDUC
 |------|---------|
 | Node.js | ≥ 20 |
 | npm | ≥ 10 |
+| @stellar/stellar-sdk | ≥ 12.0.0 (peer dependency) |
 
 ### Setup
 
@@ -172,7 +173,7 @@ const half = Number(amount) / 2;
 
 ### Soroban RPC calls
 
-All RPC calls go through `src/soroban.ts`. Do not call `SorobanRpc` directly from module files. This keeps the mock boundary clean for tests.
+All RPC calls go through `src/soroban.ts`. Do not call `SorobanRpc` directly from module files; import `rpc` from `@stellar/stellar-sdk` (v12+) instead. This keeps the mock boundary clean for tests.
 
 Read-only operations must use **simulation only** — never submit a transaction for a read:
 
@@ -188,7 +189,8 @@ await this._sendAndPoll(server, tx);
 
 - `streams.ts` orchestrates — it calls factory to resolve addresses, then calls stream contracts.
 - `factory.ts` and `governor.ts` are thin wrappers — one function per contract call.
-- `soroban.ts` is the only file that imports from `@stellar/stellar-sdk`. No other file should import stellar-sdk directly (this makes it easy to mock in tests).
+- `soroban.ts` is the primary file that imports from `@stellar/stellar-sdk`. Other source files may import specific types/functions as needed, but prefer re-exported SDK types from `soroban.ts` when possible.
+- Use the `rpc` namespace exported by `@stellar/stellar-sdk` (v12+). The legacy `SorobanRpc` alias still exists for backward compatibility, but new code must import `rpc`. An ESLint `no-restricted-imports` rule enforces this in source files.
 
 ### Exports