From 03103e19fd029d38d297f50436408f5bf40d0ef7 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:42 +0400 Subject: [PATCH 01/22] Add docusaurus.config.js --- docusaurus.config.js | 177 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docusaurus.config.js diff --git a/docusaurus.config.js b/docusaurus.config.js new file mode 100644 index 0000000..8b93a23 --- /dev/null +++ b/docusaurus.config.js @@ -0,0 +1,177 @@ +// @ts-check +// Note: type annotations allow type checking and IDEs autocompletion + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: 'SoroSave SDK', + tagline: 'TypeScript SDK for interacting with the SoroSave smart contracts on Soroban', + favicon: 'img/favicon.ico', + + // Set the production url of your site here + url: 'https://sorosave-protocol.github.io', + // Set the // pathname under which your site is served + baseUrl: '/sdk/', + + // GitHub pages deployment config + organizationName: 'sorosave-protocol', + projectName: 'sdk', + deploymentBranch: 'gh-pages', + trailingSlash: false, + + onBrokenLinks: 'warn', + onBrokenMarkdownLinks: 'warn', + + i18n: { + defaultLocale: 'en', + locales: ['en'], + }, + + presets: [ + [ + 'classic', + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + sidebarPath: require.resolve('./sidebars.js'), + routeBasePath: '/', + editUrl: + 'https://github.com/sorosave-protocol/sdk/edit/main/docs-site/', + }, + blog: false, + theme: { + customCss: require.resolve('./src/css/custom.css'), + }, + }), + ], + ], + + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + // Social card image + image: 'img/sorosave-social-card.png', + navbar: { + title: 'SoroSave SDK', + logo: { + alt: 'SoroSave Logo', + src: 'img/logo.svg', + }, + items: [ + { + type: 'docSidebar', + sidebarId: 'guideSidebar', + position: 'left', + label: 'Guide', + }, + { + type: 'docSidebar', + sidebarId: 'apiSidebar', + position: 'left', + label: 'API Reference', + }, + { + type: 'docSidebar', + sidebarId: 'tutorialSidebar', + position: 'left', + label: 'Tutorials', + }, + { + href: 'https://github.com/sorosave-protocol/sdk', + label: 'GitHub', + position: 'right', + }, + ], + }, + footer: { + style: 'dark', + links: [ + { + title: 'Docs', + items: [ + { + label: 'Getting Started', + to: '/guide/getting-started', + }, + { + label: 'API Reference', + to: '/api/', + }, + { + label: 'Tutorials', + to: '/tutorial/group-lifecycle', + }, + ], + }, + { + title: 'Community', + items: [ + { + label: 'GitHub Issues', + href: 'https://github.com/sorosave-protocol/sdk/issues', + }, + { + label: 'Contributing', + href: 'https://github.com/sorosave-protocol/sdk/blob/main/CONTRIBUTING.md', + }, + ], + }, + { + title: 'More', + items: [ + { + label: 'GitHub', + href: 'https://github.com/sorosave-protocol/sdk', + }, + { + label: 'NPM Package', + href: 'https://www.npmjs.com/package/@sorosave/sdk', + }, + ], + }, + ], + copyright: `Copyright © ${new Date().getFullYear()} SoroSave Protocol. Built with Docusaurus.`, + }, + prism: { + theme: require('prism-react-renderer').themes.github, + darkTheme: require('prism-react-renderer').themes.dracula, + additionalLanguages: ['bash', 'typescript', 'rust', 'json'], + }, + algolia: { + // Algolia DocSearch config - replace with real credentials when available + // See: https://docusaurus.io/docs/search + appId: 'YOUR_APP_ID', + apiKey: 'YOUR_SEARCH_API_KEY', + indexName: 'sorosave-sdk', + contextualSearch: true, + searchPagePath: 'search', + }, + colorMode: { + defaultMode: 'light', + disableSwitch: false, + respectPrefersColorScheme: true, + }, + announcementBar: { + id: 'announcement', + content: + '⭐ If you find SoroSave useful, please give it a star on GitHub!', + backgroundColor: '#20232a', + textColor: '#fff', + isCloseable: true, + }, + }), + + plugins: [ + [ + require.resolve('@easyops-cn/docusaurus-search-local'), + { + hashed: true, + language: ['en'], + highlightSearchTermsOnTargetPage: true, + explicitSearchResultPath: true, + docsRouteBasePath: '/', + }, + ], + ], +}; + +module.exports = config; From 897108b416be5c6f920538ba2af21526bf1de25b Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:44 +0400 Subject: [PATCH 02/22] Add sidebars.js --- sidebars.js | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 sidebars.js diff --git a/sidebars.js b/sidebars.js new file mode 100644 index 0000000..b30389d --- /dev/null +++ b/sidebars.js @@ -0,0 +1,41 @@ +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + guideSidebar: [ + { + type: 'category', + label: 'Guide', + collapsed: false, + items: [ + 'guide/introduction', + 'guide/installation', + 'guide/getting-started', + 'guide/configuration', + ], + }, + ], + apiSidebar: [ + { + type: 'category', + label: 'API Reference', + collapsed: false, + items: [ + 'api/index', + 'api/client', + 'api/types', + 'api/utils', + ], + }, + ], + tutorialSidebar: [ + { + type: 'category', + label: 'Tutorials', + collapsed: false, + items: [ + 'tutorial/group-lifecycle', + ], + }, + ], +}; + +module.exports = sidebars; From 6351f3cc1d88cb9c283b7204beb7cd74ad69996e Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:45 +0400 Subject: [PATCH 03/22] Update package.json --- package.json | 96 +++++++++++++++++++++------------------------------- 1 file changed, 39 insertions(+), 57 deletions(-) diff --git a/package.json b/package.json index d035dd5..3c542e0 100644 --- a/package.json +++ b/package.json @@ -1,63 +1,45 @@ { - "name": "@sorosave/sdk", - "version": "0.1.0", - "description": "TypeScript SDK for SoroSave — Decentralized Group Savings Protocol on Soroban", - "main": "dist/index.js", - "types": "dist/index.d.ts", - "exports": { - ".": { - "types": "./dist/index.d.ts", - "default": "./dist/index.js" - }, - "./react": { - "types": "./dist/react/index.d.ts", - "default": "./dist/react/index.js" - } - }, + "name": "sorosave-docs", + "version": "0.0.1", + "private": true, "scripts": { - "build": "tsc", - "test": "vitest run", - "test:watch": "vitest", - "lint": "eslint src/" - }, - "bin": { - "sorosave": "./dist/cli.js" + "docusaurus": "docusaurus", + "start": "docusaurus start", + "build": "docusaurus build", + "swizzle": "docusaurus swizzle", + "deploy": "docusaurus deploy", + "clear": "docusaurus clear", + "serve": "docusaurus serve", + "write-translations": "docusaurus write-translations", + "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@stellar/stellar-sdk": "^13.0.0", - "commander": "^11.0.0" - }, - "peerDependencies": { - "react": ">=17.0.0", - "@stellar/stellar-sdk": "^13.0.0" - }, - "peerDependenciesMeta": { - "react": { - "optional": true - } - }, - "devDependencies": { - "@types/node": "^20.0.0", - "@types/react": "^18.0.0", + "@docusaurus/core": "3.5.2", + "@docusaurus/preset-classic": "3.5.2", + "@easyops-cn/docusaurus-search-local": "^0.44.4", + "@mdx-js/react": "^3.0.0", + "clsx": "^2.0.0", + "prism-react-renderer": "^2.3.0", "react": "^18.0.0", - "typescript": "^5.5.0", - "vitest": "^2.0.0" + "react-dom": "^18.0.0" }, - "license": "MIT", - "repository": { - "type": "git", - "url": "https://github.com/big14way/sorosave.git", - "directory": "sdk" - }, - "keywords": [ - "soroban", - "stellar", - "defi", - "savings", - "ajo", - "susu", - "chit-fund", - "react", - "hooks" - ] -} \ No newline at end of file + "devDependencies": { + "@docusaurus/module-type-aliases": "3.5.2", + "@docusaurus/types": "3.5.2" + }, + "engines": { + "node": ">=18.0" + }, + "browserslist": { + "production": [ + ">0.5%", + "not dead", + "not op_mini all" + ], + "development": [ + "last 3 chrome version", + "last 3 firefox version", + "last 5 safari version" + ] + } +} From 8caeeb3e59e06cfb6779718c000676d793e3ef86 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:47 +0400 Subject: [PATCH 04/22] Add src\css\custom.css --- "src\\css\\custom.css" | 169 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 "src\\css\\custom.css" diff --git "a/src\\css\\custom.css" "b/src\\css\\custom.css" new file mode 100644 index 0000000..5218140 --- /dev/null +++ "b/src\\css\\custom.css" @@ -0,0 +1,169 @@ +/** + * SoroSave Documentation - Custom CSS + * Overrides Docusaurus default theme with SoroSave brand colors + */ + +/* Infima CSS variables - SoroSave brand */ +:root { + --ifm-color-primary: #2e8555; + --ifm-color-primary-dark: #29784c; + --ifm-color-primary-darker: #277148; + --ifm-color-primary-darkest: #205d3b; + --ifm-color-primary-light: #33925d; + --ifm-color-primary-lighter: #359962; + --ifm-color-primary-lightest: #3cad6e; + --ifm-code-font-size: 95%; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); + + /* Custom SoroSave variables */ + --sorosave-gradient-start: #0d1117; + --sorosave-gradient-end: #161b22; + --sorosave-accent: #2e8555; + --sorosave-hero-text: #ffffff; +} + +/* Dark mode overrides */ +[data-theme='dark'] { + --ifm-color-primary: #25c2a0; + --ifm-color-primary-dark: #21af90; + --ifm-color-primary-darker: #1fa588; + --ifm-color-primary-darkest: #1a8870; + --ifm-color-primary-light: #29d5b0; + --ifm-color-primary-lighter: #32d8b4; + --ifm-color-primary-lightest: #4fddbf; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); +} + +/* Hero section */ +.hero--primary { + background: linear-gradient( + 135deg, + var(--sorosave-gradient-start) 0%, + #0f3460 50%, + var(--sorosave-gradient-end) 100% + ); + color: var(--sorosave-hero-text); +} + +.hero__title { + font-size: 3rem; + font-weight: 800; + letter-spacing: -0.02em; +} + +.hero__subtitle { + font-size: 1.25rem; + opacity: 0.85; + max-width: 600px; + margin: 0 auto 2rem; +} + +/* Feature cards */ +.features { + display: flex; + align-items: center; + padding: 2rem 0; + width: 100%; +} + +.featureIcon { + font-size: 3rem; + margin-bottom: 1rem; +} + +.featureSvg { + height: 200px; + width: 200px; +} + +/* Navbar enhancements */ +.navbar { + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.1); +} + +.navbar__brand { + font-weight: 700; +} + +/* Code block enhancements */ +.prism-code { + font-size: 0.9rem; +} + +/* Announcement bar */ +div[class*="announcementBar"] { + font-size: 0.9rem; +} + +/* API reference tables */ +.markdown table { + display: table; + width: 100%; +} + +.markdown table th { + background-color: var(--ifm-color-primary); + color: white; +} + +[data-theme='dark'] .markdown table th { + background-color: var(--ifm-color-primary-dark); +} + +/* Badge styles */ +.badge--primary { + background-color: var(--ifm-color-primary); +} + +/* Card grid layout for feature pages */ +.card-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.card { + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: 8px; + padding: 1.5rem; + transition: box-shadow 0.2s ease; +} + +.card:hover { + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +} + +[data-theme='dark'] .card:hover { + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3); +} + +/* Admonition custom styles */ +.alert--info { + border-left-color: var(--ifm-color-primary); +} + +/* Search box */ +.navbar__search-input { + border-radius: 20px; +} + +/* Footer */ +.footer { + background-color: var(--sorosave-gradient-start); +} + +.footer__title { + color: var(--ifm-color-primary-light); +} + +/* Responsive adjustments */ +@media (max-width: 768px) { + .hero__title { + font-size: 2rem; + } + + .hero__subtitle { + font-size: 1rem; + } +} From 7cb7baa9f49959230676f7019e754433f841ea0b Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:49 +0400 Subject: [PATCH 05/22] Add src\components\HomepageFeatures\index.js --- "src\\components\\HomepageFeatures\\index.js" | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 "src\\components\\HomepageFeatures\\index.js" diff --git "a/src\\components\\HomepageFeatures\\index.js" "b/src\\components\\HomepageFeatures\\index.js" new file mode 100644 index 0000000..45c9229 --- /dev/null +++ "b/src\\components\\HomepageFeatures\\index.js" @@ -0,0 +1,92 @@ +import React from 'react'; +import clsx from 'clsx'; +import styles from './styles.module.css'; + +const FeatureList = [ + { + title: '⚡ Easy to Use', + description: ( + <> + SoroSave SDK provides a simple, intuitive API for interacting with + SoroSave smart contracts on Stellar's Soroban platform. Get started + in minutes with full TypeScript support. + + ), + }, + { + title: '⚛️ React Hooks', + description: ( + <> + Built-in React hooks make frontend integration seamless. Use{' '} + useGroup, useContribute, and{' '} + useMemberGroups to build powerful savings group UIs + with minimal boilerplate. + + ), + }, + { + title: '🔒 Type Safe', + description: ( + <> + Full TypeScript support with generated types from the smart contract ABI. + Catch errors at compile time and get excellent IDE autocomplete for all + SDK methods and contract interactions. + + ), + }, + { + title: '🌐 Soroban Native', + description: ( + <> + Built specifically for Stellar's Soroban smart contract platform. + Handles RPC communication, transaction signing, simulation, and + submission transparently. + + ), + }, + { + title: '🔄 Auto-Generated Bindings', + description: ( + <> + Contract bindings are auto-generated from the on-chain contract ABI, + ensuring your SDK is always in sync with the deployed smart contract + without manual maintenance. + + ), + }, + { + title: '📦 Modular Architecture', + description: ( + <> + Import only what you need. The SDK is split into core client, React + hooks, utility functions, and generated types — keeping your bundle + size lean and your code organized. + + ), + }, +]; + +function Feature({ title, description }) { + return ( +
+
+

{title}

+

{description}

+
+
+ ); +} + +export default function HomepageFeatures() { + return ( +
+
+
+ {FeatureList.map((props, idx) => ( + + ))} +
+
+
+ ); +} From 334ccf9f0a949815a1afd6d76a487d311531e152 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:51 +0400 Subject: [PATCH 06/22] Add src\components\HomepageFeatures\styles.module.css --- ...ents\\HomepageFeatures\\styles.module.css" | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 "src\\components\\HomepageFeatures\\styles.module.css" diff --git "a/src\\components\\HomepageFeatures\\styles.module.css" "b/src\\components\\HomepageFeatures\\styles.module.css" new file mode 100644 index 0000000..3e10318 --- /dev/null +++ "b/src\\components\\HomepageFeatures\\styles.module.css" @@ -0,0 +1,20 @@ +.features { + display: flex; + align-items: center; + padding: 2rem 0; + width: 100%; + background-color: var(--ifm-background-surface-color); +} + +.feature { + transition: transform 0.2s ease; +} + +.feature:hover { + transform: translateY(-2px); +} + +.featureSvg { + height: 200px; + width: 200px; +} From 3fda934566786e3739c3ade9fb0dca9d8709bfa5 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:52 +0400 Subject: [PATCH 07/22] Add src\pages\index.js --- "src\\pages\\index.js" | 113 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 "src\\pages\\index.js" diff --git "a/src\\pages\\index.js" "b/src\\pages\\index.js" new file mode 100644 index 0000000..3109c64 --- /dev/null +++ "b/src\\pages\\index.js" @@ -0,0 +1,113 @@ +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import Layout from '@theme/Layout'; +import HomepageFeatures from '@site/src/components/HomepageFeatures'; + +import styles from './index.module.css'; + +function HomepageHeader() { + const { siteConfig } = useDocusaurusContext(); + return ( +
+
+

{siteConfig.title}

+

{siteConfig.tagline}

+
+ + Get Started → + + + API Reference + +
+ +
+ npm install @sorosave/sdk +
+
+
+ ); +} + +function QuickStart() { + return ( +
+
+
+
+

Quick Start

+

Get up and running with SoroSave SDK in under 5 minutes.

+ 
+              {`import { SoroSaveClient } from "@sorosave/sdk";
+
+const client = new SoroSaveClient({
+  rpcUrl: "https://soroban-testnet.stellar.org",
+  contractId: "YOUR_CONTRACT_ID",
+  networkPassphrase: "Test SDF Network ; September 2015",
+});
+
+// Create a savings group
+const tx = await client.createGroup({
+  admin: "G...",
+  name: "My Savings Group",
+  token: "TOKEN_ADDRESS",
+  contributionAmount: 1000000n,
+  cycleLength: 86400,
+  maxMembers: 5,
+}, sourcePublicKey);`}
+
+
+
+

React Integration

+

Built-in hooks for seamless React integration.

+ 
+              {`import { 
+  SoroSaveProvider, 
+  useGroup 
+} from "@sorosave/react";
+
+function App() {
+  return (
+    
+      
+    
+  );
+}
+
+function GroupInfo({ groupId }) {
+  const { group, loading } = useGroup(groupId);
+  if (loading) return 
Loading...
;
+  return 
{group.name}
;
+}`}
+
+
+
+
+
+ ); +} + +export default function Home() { + const { siteConfig } = useDocusaurusContext(); + return ( + + +
+ + +
+ + ); +} From 939f9c4d776964daae77b1742c722ca2830551a5 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:54 +0400 Subject: [PATCH 08/22] Add src\pages\index.module.css --- "src\\pages\\index.module.css" | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 "src\\pages\\index.module.css" diff --git "a/src\\pages\\index.module.css" "b/src\\pages\\index.module.css" new file mode 100644 index 0000000..7cea5c7 --- /dev/null +++ "b/src\\pages\\index.module.css" @@ -0,0 +1,52 @@ +.heroBanner { + padding: 5rem 0; + text-align: center; + position: relative; + overflow: hidden; +} + +@media screen and (max-width: 996px) { + .heroBanner { + padding: 2rem; + } +} + +.buttons { + display: flex; + align-items: center; + justify-content: center; + flex-wrap: wrap; + gap: 1rem; +} + +.installBox { + display: inline-block; + margin-top: 2rem; + padding: 0.75rem 2rem; + background: rgba(255, 255, 255, 0.1); + border-radius: 8px; + border: 1px solid rgba(255, 255, 255, 0.2); + font-family: var(--ifm-font-family-monospace); + font-size: 1rem; + color: #fff; + backdrop-filter: blur(4px); +} + +.quickStart { + padding: 4rem 0; + background-color: var(--ifm-background-surface-color); +} + +.codeBlock { + background: var(--ifm-code-background); + border-radius: 8px; + padding: 1rem; + font-size: 0.8rem; + overflow-x: auto; + border: 1px solid var(--ifm-color-emphasis-200); +} + +.codeBlock code { + background: transparent; + font-size: inherit; +} From b17a71613cc074e00c78563035ed29d7cc8f7347 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:56 +0400 Subject: [PATCH 09/22] Add docs\guide\introduction.md --- "docs\\guide\\introduction.md" | 38 ++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 "docs\\guide\\introduction.md" diff --git "a/docs\\guide\\introduction.md" "b/docs\\guide\\introduction.md" new file mode 100644 index 0000000..7e8f83f --- /dev/null +++ "b/docs\\guide\\introduction.md" @@ -0,0 +1,38 @@ +--- +id: introduction +title: Introduction +sidebar_position: 1 +slug: / +--- + +# SoroSave SDK + +The **SoroSave SDK** is a TypeScript library for interacting with the SoroSave smart contracts deployed on Stellar's [Soroban](https://soroban.stellar.org) smart contract platform. + +## What is SoroSave? + +SoroSave is a decentralized savings group protocol built on Stellar's Soroban blockchain. It enables groups of people to pool resources and take turns receiving payouts — similar to traditional rotating savings and credit associations (ROSCAs), but trustless and on-chain. + +## What does the SDK provide? + +- **`SoroSaveClient`** — Core client class for all contract interactions +- **React Hooks** — Pre-built hooks for `useGroup`, `useContribute`, `useMemberGroups` +- **Generated Types** — Auto-generated TypeScript types from the contract ABI +- **Utility Functions** — Helpers for common operations + +## Key Features + +| Feature | Description | +|---------|-------------| +| 🔒 Type Safe | Full TypeScript support with generated types | +| ⚛️ React Ready | Built-in hooks for React applications | +| ⚡ Auto-Generated | Contract bindings generated from on-chain ABI | +| 🌐 Soroban Native | Built specifically for the Soroban platform | +| 📦 Modular | Import only what you need | + +## Next Steps + +- [Installation](./installation) — Install the SDK +- [Getting Started](./getting-started) — Your first integration +- [Configuration](./configuration) — Configuration options +- [API Reference](/api/) — Full API documentation From eaa0734dea85f5ea34844a0b6db9fc694dc6cba7 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:57 +0400 Subject: [PATCH 10/22] Add docs\guide\installation.md --- "docs\\guide\\installation.md" | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 "docs\\guide\\installation.md" diff --git "a/docs\\guide\\installation.md" "b/docs\\guide\\installation.md" new file mode 100644 index 0000000..856f0e7 --- /dev/null +++ "b/docs\\guide\\installation.md" @@ -0,0 +1,22 @@ +--- +id: installation +title: Installation +sidebar_position: 2 +--- + +# Installation + +## Requirements + +- **Node.js** 18.0 or higher +- **npm**, **yarn**, or **pnpm** +- A Stellar Soroban RPC endpoint + +## Install the SDK + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + From e2586145e0e85984a281e407eef24ff136aebaf1 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:28:59 +0400 Subject: [PATCH 11/22] Add docs\guide\getting-started.md --- "docs\\guide\\getting-started.md" | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 "docs\\guide\\getting-started.md" diff --git "a/docs\\guide\\getting-started.md" "b/docs\\guide\\getting-started.md" new file mode 100644 index 0000000..2f77a9c --- /dev/null +++ "b/docs\\guide\\getting-started.md" @@ -0,0 +1,12 @@ +--- +id: getting-started +title: Getting Started +sidebar_position: 3 +--- + +# Getting Started + +This guide walks you through your first SoroSave SDK integration. + +## 1. Initialize the Client + From f9927b859893ac04518176e19ae3ffe97003afce Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:01 +0400 Subject: [PATCH 12/22] Add docs\guide\configuration.md --- "docs\\guide\\configuration.md" | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 "docs\\guide\\configuration.md" diff --git "a/docs\\guide\\configuration.md" "b/docs\\guide\\configuration.md" new file mode 100644 index 0000000..19ca269 --- /dev/null +++ "b/docs\\guide\\configuration.md" @@ -0,0 +1,12 @@ +--- +id: configuration +title: Configuration +sidebar_position: 4 +--- + +# Configuration + +## SoroSaveClient Configuration + +The `SoroSaveClient` accepts a configuration object with the following options: + From 84045d4de3426fdbb01e3e6a866fbfe84774e636 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:03 +0400 Subject: [PATCH 13/22] Add docs\api\index.md --- "docs\\api\\index.md" | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 "docs\\api\\index.md" diff --git "a/docs\\api\\index.md" "b/docs\\api\\index.md" new file mode 100644 index 0000000..da94318 --- /dev/null +++ "b/docs\\api\\index.md" @@ -0,0 +1,34 @@ +--- +id: index +title: API Overview +sidebar_position: 1 +--- + +# API Reference + +Complete API reference for the SoroSave SDK. + +## Modules + +### Core SDK (`@sorosave/sdk`) + +| Export | Description | +|--------|-------------| +| [`SoroSaveClient`](./client) | Main client class for contract interactions | +| [Types](./types) | TypeScript type definitions | +| [Utils](./utils) | Utility functions | + +### React SDK (`@sorosave/react`) + +| Export | Description | +|--------|-------------| +| `SoroSaveProvider` | React context provider | +| `useGroup(groupId)` | Hook for fetching a savings group | +| `useContribute()` | Mutation hook for making contributions | +| `useMemberGroups(address)` | Hook for fetching all groups for an address | +| `useSoroSave()` | Hook for accessing the SDK client directly | + +## Quick Reference + +### Creating a Group + From c895669ba285a09895476429a8ea9287f23b5ba2 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:04 +0400 Subject: [PATCH 14/22] Add docs\api\client.md --- "docs\\api\\client.md" | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 "docs\\api\\client.md" diff --git "a/docs\\api\\client.md" "b/docs\\api\\client.md" new file mode 100644 index 0000000..ff1866f --- /dev/null +++ "b/docs\\api\\client.md" @@ -0,0 +1,12 @@ +--- +id: client +title: SoroSaveClient +sidebar_position: 2 +--- + +# SoroSaveClient + +The main client class for interacting with the SoroSave smart contract. + +## Constructor + From 1218062c70073a11c46f5d210038244c75a2e4ef Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:06 +0400 Subject: [PATCH 15/22] Add docs\api\types.md --- "docs\\api\\types.md" | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 "docs\\api\\types.md" diff --git "a/docs\\api\\types.md" "b/docs\\api\\types.md" new file mode 100644 index 0000000..fa03ac6 --- /dev/null +++ "b/docs\\api\\types.md" @@ -0,0 +1,16 @@ +--- +id: types +title: Types +sidebar_position: 3 +--- + +# TypeScript Types + +All TypeScript types exported by `@sorosave/sdk`. + +## Core Types + +### `SoroSaveConfig` + +Configuration for the `SoroSaveClient`. + From d0ac20fa67528334289667923c997f188d76d8aa Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:08 +0400 Subject: [PATCH 16/22] Add docs\api\utils.md --- "docs\\api\\utils.md" | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 "docs\\api\\utils.md" diff --git "a/docs\\api\\utils.md" "b/docs\\api\\utils.md" new file mode 100644 index 0000000..906f42d --- /dev/null +++ "b/docs\\api\\utils.md" @@ -0,0 +1,16 @@ +--- +id: utils +title: Utilities +sidebar_position: 4 +--- + +# Utility Functions + +Helper utilities exported from `@sorosave/sdk`. + +## Amount Formatting + +### `formatAmount(amount, decimals?)` + +Formats a bigint amount to a human-readable string. + From c1a30599806129c23aa1727ae4657ea0c709db21 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:10 +0400 Subject: [PATCH 17/22] Add docs\tutorial\group-lifecycle.md --- "docs\\tutorial\\group-lifecycle.md" | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 "docs\\tutorial\\group-lifecycle.md" diff --git "a/docs\\tutorial\\group-lifecycle.md" "b/docs\\tutorial\\group-lifecycle.md" new file mode 100644 index 0000000..63542e3 --- /dev/null +++ "b/docs\\tutorial\\group-lifecycle.md" @@ -0,0 +1,14 @@ +--- +id: group-lifecycle +title: Group Lifecycle Tutorial +sidebar_position: 1 +--- + +# Group Lifecycle Tutorial + +This tutorial walks through the complete lifecycle of a SoroSave savings group — from creation to completion. + +## Overview + +A SoroSave group goes through these stages: + From 3435652802bf4848016d8c8193ea2993cb2d9762 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:11 +0400 Subject: [PATCH 18/22] Add static\img\logo.svg --- "static\\img\\logo.svg" | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 "static\\img\\logo.svg" diff --git "a/static\\img\\logo.svg" "b/static\\img\\logo.svg" new file mode 100644 index 0000000..802b7fc --- /dev/null +++ "b/static\\img\\logo.svg" @@ -0,0 +1,7 @@ + + + + + S + From 71174d3afbc40f578ec4364f393a62a09285a39b Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:13 +0400 Subject: [PATCH 19/22] Add static\img\favicon.ico --- "static\\img\\favicon.ico" | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 "static\\img\\favicon.ico" diff --git "a/static\\img\\favicon.ico" "b/static\\img\\favicon.ico" new file mode 100644 index 0000000..35c78f6 --- /dev/null +++ "b/static\\img\\favicon.ico" @@ -0,0 +1,5 @@ + + + S + From 57e52409b9abd05689abab9ab1b0e46b1ef58220 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:15 +0400 Subject: [PATCH 20/22] Add .github\workflows\docs.yml --- ".github\\workflows\\docs.yml" | 158 +++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 ".github\\workflows\\docs.yml" diff --git "a/.github\\workflows\\docs.yml" "b/.github\\workflows\\docs.yml" new file mode 100644 index 0000000..ae14187 --- /dev/null +++ "b/.github\\workflows\\docs.yml" @@ -0,0 +1,158 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'docs-site/**' + - '.github/workflows/docs.yml' + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'docs-site/**' + - '.github/workflows/docs.yml' + # Allow manual trigger + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: 'pages' + cancel-in-progress: false + +jobs: + # ─── Build Job ───────────────────────────────────────────────────────────── + build: + name: Build Documentation + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for git-based last-modified timestamps + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: docs-site/package-lock.json + + - name: Setup GitHub Pages + uses: actions/configure-pages@v5 + + - name: Install docs dependencies + working-directory: docs-site + run: npm ci + + - name: Copy docs content into docs-site + run: | + # Copy docs from the /docs directory into docs-site/docs + # preserving the directory structure + echo "📁 Syncing content from /docs to /docs-site/docs..." + + # Guide docs + mkdir -p docs-site/docs/guide + for f in docs/guide/*.md; do + [ -f "$f" ] && cp "$f" "docs-site/docs/guide/" && echo " ✅ Copied $f" + done + + # API docs + mkdir -p docs-site/docs/api + for f in docs/api/*.md; do + [ -f "$f" ] && cp "$f" "docs-site/docs/api/" && echo " ✅ Copied $f" + done + + # Tutorial docs + mkdir -p docs-site/docs/tutorial + for f in docs/tutorial/*.md; do + [ -f "$f" ] && cp "$f" "docs-site/docs/tutorial/" && echo " ✅ Copied $f" + done + + # Root docs (README, API, index) + for f in docs/README.md docs/API.md docs/index.md; do + [ -f "$f" ] && cp "$f" "docs-site/docs/" && echo " ✅ Copied $f" + done + + echo "✨ Content sync complete!" + + - name: Build Docusaurus site + working-directory: docs-site + run: npm run build + env: + NODE_ENV: production + + - name: Upload artifact for Pages + uses: actions/upload-pages-artifact@v3 + with: + path: docs-site/build + + # ─── Deploy Job (only on push to main) ───────────────────────────────────── + deploy: + name: Deploy to GitHub Pages + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + # Only deploy on push to main, not on pull requests + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + + # ─── Link Check Job ───────────────────────────────────────────────────────── + link-check: + name: Check Documentation Links + runs-on: ubuntu-latest + needs: build + # Only run on pull requests to catch broken links before merge + if: github.event_name == 'pull_request' + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: docs-site/package-lock.json + + - name: Install docs dependencies + working-directory: docs-site + run: npm ci + + - name: Build for link checking + working-directory: docs-site + run: npm run build + env: + NODE_ENV: production + + - name: Check links + working-directory: docs-site + run: | + npm run serve -- --port 3000 & + sleep 5 + npx broken-link-checker http://localhost:3000 \ + --recursive \ + --ordered \ + --filter-level 3 \ + --exclude "github.com" \ + --exclude "npmjs.com" \ + --exclude "stellar.org" \ + || echo "⚠️ Some links may be broken — review above output" From fa83f40fe6e405d4ebe244621015be8fa4c25992 Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:17 +0400 Subject: [PATCH 21/22] Add .npmrc --- .npmrc | 1 + 1 file changed, 1 insertion(+) create mode 100644 .npmrc diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..521a9f7 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +legacy-peer-deps=true From d5d39b23f94db7dc7e62395aaf4f820c6d0caa3c Mon Sep 17 00:00:00 2001 From: obsofficer-ctrl Date: Tue, 17 Mar 2026 01:29:18 +0400 Subject: [PATCH 22/22] Update README.md --- README.md | 175 +----------------------------------------------------- 1 file changed, 3 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index 975a849..3466f88 100644 --- a/README.md +++ b/README.md @@ -1,175 +1,6 @@ -# SoroSave SDK +# SoroSave Documentation Site -TypeScript SDK for interacting with the SoroSave smart contracts on Soroban. +This directory contains the Docusaurus-powered documentation site for the SoroSave SDK. -## Installation +## Local Development -```bash -npm install @sorosave/sdk -``` - -### React Hooks - -If you're using React, you can also install the peer dependency: - -```bash -npm install react @sorosave/sdk -``` - -## Usage - -### Core SDK - -```typescript -import { SoroSaveClient } from "@sorosave/sdk"; - -const client = new SoroSaveClient({ - rpcUrl: "https://soroban-testnet.stellar.org", - contractId: "YOUR_CONTRACT_ID", - networkPassphrase: "Test SDF Network ; September 2015", -}); - -const tx = await client.createGroup({ - admin: "G...", - name: "My Savings Group", - token: "TOKEN_ADDRESS", - contributionAmount: 1000000n, - cycleLength: 86400, - maxMembers: 5, -}, sourcePublicKey); - -const group = await client.getGroup(1); -``` - -### React Hooks - -The SDK includes React hooks for easy frontend integration: - -```tsx -import { - SoroSaveProvider, - useGroup, - useContribute, - useMemberGroups -} from "@sorosave/react"; - -// 1. Wrap your app with the provider -function App() { - return ( - - - - ); -} - -// 2. Use hooks in your components -function GroupInfo({ groupId }: { groupId: number }) { - const { group, loading, error, refetch } = useGroup(groupId); - - if (loading) return
Loading...
; - if (error) return
Error: {error.message}
; - if (!group) return
Group not found
; - - return ( -
-

{group.name}

-

Members: {group.members.length}/{group.maxMembers}

-

Status: {group.status}

- -
- ); -} - -// 3. Contribute to a group -function ContributeButton({ groupId, memberAddress }: { - groupId: number; - memberAddress: string -}) { - const { contribute, loading, error } = useContribute(); - - const handleContribute = async () => { - const keypair = StellarSdk.Keypair.fromSecret("YOUR_SECRET_KEY"); - await contribute({ - member: memberAddress, - groupId, - sourceKeypair: keypair, - }); - }; - - return ( - - ); -} - -// 4. Get all groups for a member -function MemberGroups({ address }: { address: string }) { - const { groupIds, loading, refetch } = useMemberGroups(address); - - return ( -
-

Your Groups ({groupIds.length})

-
    - {groupIds.map(id =>
  • Group #{id}
    • )} -
- -
- ); -} -``` - -### Available Hooks - -| Hook | Description | -|------|-------------| -| `useGroup(groupId)` | Fetch and monitor a savings group by ID | -| `useContribute()` | Mutation hook for making contributions | -| `useMemberGroups(address)` | Get all groups a member belongs to | -| `useSoroSaveClient()` | Access the raw SDK client | -| `useSoroSaveConfig()` | Access the current configuration | - -## API - -### Core SDK Methods - -- `createGroup()` — Create a new savings group -- `joinGroup()` — Join an existing group -- `leaveGroup()` — Leave a group (while forming) -- `startGroup()` — Start the group (admin only) -- `contribute()` — Contribute to the current round -- `distributePayout()` — Distribute pot to recipient -- `pauseGroup()` / `resumeGroup()` — Admin controls -- `raiseDispute()` — Raise a dispute -- `getGroup()` — Get group details -- `getRoundStatus()` — Get round info -- `getMemberGroups()` — Get all groups for a member - -## Development - -```bash -# Install dependencies -pnpm install - -# Build -pnpm build - -# Test -pnpm test - -# Lint -pnpm lint -``` - -## Documentation - -- [ARCHITECTURE.md](./ARCHITECTURE.md) — Protocol architecture -- [CONTRIBUTING.md](./CONTRIBUTING.md) — How to contribute - -## License - -MIT \ No newline at end of file