docs(faq): expand FAQ.md with 20+ entries (#793) - #846
Open
Wycode569 wants to merge 1 commit into
Open
Conversation
|
@Wycode569 is attempting to deploy a commit to the ritik4ever's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
@Wycode569 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! 🚀 |
📝 WalkthroughWalkthroughFAQ.md was expanded into a categorized guide for users and developers. It documents stream workflows, technical behavior, local setup, contract configuration, and troubleshooting procedures. ChangesFAQ Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@FAQ.md`:
- Around line 60-63: Align the FAQ’s workflow descriptions with the
implementation status: update the cancellation refund and Freighter claim
sections around the referenced workflows to mark them as planned if they are not
currently live, or revise the “Is StellarStream production-ready?” limitations
to accurately state that these flows are implemented. Keep the documented status
consistent across the affected sections.
- Line 80: The FAQ formulas around the vesting calculation must not imply funds
are claimable during a cliff. Scope the displayed formulas to cliffSeconds = 0,
or add the start_time + cliffSeconds claimability gate; alternatively, direct
readers to the cliff-adjusted model in docs/STREAM_MATH.md while preserving the
existing FAQ explanation.
- Around line 207-213: Update the WebSocket debugging instructions to reference
the configured backend URL using the configured port rather than hardcoded 3001,
and include the /api/ws path. Keep the surrounding DevTools and reconnection
guidance unchanged.
- Around line 90-97: Update the claim flow description under “How do I claim
funds from a stream?” to use the canonical recipient-inclusive signature
`claim(streamId, recipientAddress, amount)`, or explicitly explain that the
frontend wrapper supplies the recipient address. Keep the contract method
description in “Can I claim partial amounts…” consistent with this signature.
- Around line 144-146: Update the development startup instructions in FAQ.md to
explicitly state that npm run dev:backend and npm run dev:frontend must be run
in separate terminals, since the backend command remains active. Do not change
the commands themselves.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+60
to
+63
| StellarStream itself does not levy a protocol fee on stream creation, claims, or cancellation in the current MVP. You still pay standard Stellar network transaction fees (typically a small fraction of a lumen) for any on-chain operation submitted through your wallet, since every `create_stream`, `claim`, and `cancel` call is a Soroban contract invocation. Budget for these network fees separately from the streamed asset amount. | ||
|
|
||
| ### Is StellarStream production-ready? | ||
| Not yet — treat it as an MVP. Per the [README's Known Limitations](README.md#10-known-limitations), the Soroban contract is not yet fully wired to the backend's execution path for token transfers, there is no authentication layer on write endpoints by default, and wallet-signed transaction flows are still being built out in the UI. See [SECURITY.md](SECURITY.md) for the current self-audit checklist and how to report vulnerabilities before relying on this for real funds. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align implementation status with the documented workflows.
Lines 60-63 state that token transfers are not wired into the backend and wallet-signed flows are still being built. Lines 71-74 and 90-91 describe cancellation refunds and Freighter claims as usable flows. Mark these flows as planned if they are not live, or update the limitation text if they are live.
Also applies to: 71-74, 90-91
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@FAQ.md` around lines 60 - 63, Align the FAQ’s workflow descriptions with the
implementation status: update the cancellation refund and Freighter claim
sections around the referenced workflows to mark them as planned if they are not
currently live, or revise the “Is StellarStream production-ready?” limitations
to accurately state that these flows are implemented. Keep the documented status
consistent across the affected sections.
| Yes. Pass an optional `startAt` field (Unix seconds) when creating a stream. Until that time is reached, the stream's status is `scheduled` and nothing is claimable; once `startAt` passes, it automatically becomes `active` and vesting begins. | ||
|
|
||
| ### What is a cliff period and how do I use it? | ||
| A cliff (`cliffSeconds`) delays the start of claimable vesting until an initial milestone has passed, even though the stream is technically active. This is useful for contractor or grant streams where you want to confirm early deliverables before any funds become claimable — see the "Contractor Vesting (Milestone & Cliff Streaming)" use case in [`docs/USE_CASES.md`](docs/USE_CASES.md#2-contractor-vesting-milestone--cliff-streaming) for a complete example. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 8 'cliffSeconds|claimable|vested|t_start|STREAM_MATH' docs backend contractsRepository: ritik4ever/stellar-stream
Length of output: 50382
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "FAQ.md relevant lines"
sed -n '70,125p' FAQ.md
echo
echo "contracts/src/lib.rs vesting and cliff implementation"
sed -n '858,910p' contracts/src/lib.rs
echo
echo "contracts/src/lib.rs claimable implementation"
sed -n '494,512p' contracts/src/lib.rs
echo
echo "Focused tests around cliff"
rg -n -C 6 "cliff|cliff_seconds|cliffSeconds|paused" contracts/src tests backend docs || trueRepository: ritik4ever/stellar-stream
Length of output: 50384
Clarify in FAQ.md that the shown formula excludes cliffs.
The cliff sections say no funds are claimable before start_time + cliffSeconds, but the main FAQ formulas calculate elapsed time from t_start and can show positive A_vested during the cliff. Scope those formulas to cliffSeconds = 0, add the cliff gate, or direct readers to the cliff-adjusted model in docs/STREAM_MATH.md.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@FAQ.md` at line 80, The FAQ formulas around the vesting calculation must not
imply funds are claimable during a cliff. Scope the displayed formulas to
cliffSeconds = 0, or add the start_time + cliffSeconds claimability gate;
alternatively, direct readers to the cliff-adjusted model in docs/STREAM_MATH.md
while preserving the existing FAQ explanation.
Comment on lines
+90
to
+97
| ### How do I claim funds from a stream? | ||
| In the dashboard, open the stream and click "Claim." Under the hood, the frontend fetches the current claimable amount from `GET /api/streams/:id`, then asks your connected Freighter wallet to sign a `claim(streamId, amount)` transaction, which is submitted to the Soroban contract. Once confirmed on-chain, the indexer picks up the `Claimed` event and updates the stream's history. | ||
|
|
||
| ### How much of a stream can I claim right now? | ||
| Claimable balance grows continuously and linearly between the stream's start and end times (see [How does the vesting math work?](#how-does-the-vesting-math-work)). You can check the live claimable amount via `GET /api/streams/:id`, or read it directly from the contract using `claimable(stream_id, at_time)`. | ||
|
|
||
| ### Can I claim partial amounts instead of the full claimable balance? | ||
| Yes. The contract's `claim(stream_id, recipient, amount)` method accepts a specific amount up to the current claimable balance — you are not required to withdraw the full vested amount in a single transaction. You can claim smaller amounts more frequently if you prefer. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 8 '\bclaim\s*\(' contracts backend frontend docsRepository: ritik4ever/stellar-stream
Length of output: 50383
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '--- FAQ relevant lines ---\n'
nl -ba FAQ.md | sed -n '85,100p'
printf '\n--- contractClient claim implementation candidates ---\n'
fd -a . frontend | sed 's#^\./##' | rg 'contractClient|wallet|claim|Claim' || true
printf '\n--- frontend claim-related files ---\n'
rg -n -C 12 'async function|function |const .*claim|claim\(' frontend/src | rg -C 4 '(function|const|claim|recipientAddress|await).*claim|claim\(' || trueRepository: ritik4ever/stellar-stream
Length of output: 254
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- FAQ relevant lines ---'
nl -ba FAQ.md | sed -n '85,100p'
printf '%s\n' ''
printf '%s\n' '--- frontend contract claim-related definitions ---'
rg -n -C 8 'async function handleClaim|function handleClaim|const handleClaim|streamContract\.claim|contractClient|claim\(' frontend/src docs/CONTRACT_BINDINGS.md
printf '%s\n' ''
printf '%s\n' '--- contractClient candidate files ---'
fd -e ts -e tsx . frontend/src -x sh -c 'echo "--- $1"; wc -l "$1"; ast-grep outline "$1" 2>/dev/null | sed -n "1,80p"' sh {}Repository: ritik4ever/stellar-stream
Length of output: 230
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- FAQ relevant lines ---'
awk 'NR>=85 && NR<=100 { printf "%6d %s\n", NR, $0 }' FAQ.md
printf '%s\n' ''
printf '%s\n' '--- frontend handleClaim and contract binding calls ---'
grep -RIn -C 8 'handleClaim\|streamContract\.claim\|\.claim(' frontend/src docs/CONTRACT_BINDINGS.md || true
printf '%s\n' ''
printf '%s\n' '--- frontend source files ---'
find frontend/src -maxdepth 3 -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) | sortRepository: ritik4ever/stellar-stream
Length of output: 26771
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- frontend/src/hooks/useClaimStream.ts ---'
awk 'NR>=1 && NR<=240 { printf "%6d %s\n", NR, $0 }' frontend/src/hooks/useClaimStream.ts
printf '%s\n' ''
printf '%s\n' '--- frontend/src/services/contractClient.ts'
awk 'NR>=1 && NR<=220 { printf "%6d %s\n", NR, $0 }' frontend/src/services/contractClient.ts
printf '%s\n' ''
printf '%s\n' '--- frontend/components ClaimButton definition ---'
fgrep -n 'function ClaimButton\|const ClaimButton\|export function ClaimButton\|export const ClaimButton' frontend/src -R || trueRepository: ritik4ever/stellar-stream
Length of output: 5367
Use one canonical claim description.
Line 91 says the frontend signs claim(streamId, amount), but the contract binding and the rest of this section use the recipient-inclusive signature. Either update line 91 to claim(streamId, recipientAddress, amount) or state explicitly that the frontend wrapper supplies recipientAddress.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@FAQ.md` around lines 90 - 97, Update the claim flow description under “How do
I claim funds from a stream?” to use the canonical recipient-inclusive signature
`claim(streamId, recipientAddress, amount)`, or explicitly explain that the
frontend wrapper supplies the recipient address. Keep the contract method
description in “Can I claim partial amounts…” consistent with this signature.
Comment on lines
+144
to
+146
| # Start frontend and backend in development mode | ||
| npm run dev:backend | ||
| npm run dev:frontend |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== package scripts =="
node - <<'JS'
const fs = require('fs');
for (const p of ['package.json','package-lock.json','npm-shrinkwrap.json']) {
if (fs.existsSync(p)) {
console.log(`--- ${p} ---`);
const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
if (p === 'package.json') {
console.log(JSON.stringify(pkg.scripts || {}, null, 2));
}
}
}
JS
echo
echo "== FAQ relevant section =="
if [ -f FAQ.md ]; then
nl -ba FAQ.md | sed -n '130,155p'
else
echo "FAQ.md not found"
fi
echo
echo "== related dev: scripts =="
rg -n --hidden -S '^"dev:(backend|frontend)"|npm run dev:backend|npm run dev:frontend|vite|nodemon|concurrently|forever|pm2' .Repository: ritik4ever/stellar-stream
Length of output: 759
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate package files =="
find . -maxdepth 3 \( -path '*/backend/package.json' -o -path '*/frontend/package.json' -o -path '*/FAQ.md' \( -empty -o ! -empty \) \) | sort
echo
echo "== backend/frontend dev scripts =="
for f in backend/package.json frontend/package.json; do
if [ -f "$f" ]; then
echo "--- $f ---"
python3 - <<'PY' "$f"
import json, sys
p=sys.argv[1]
data=json.load(open(p, encoding='utf-8'))
print(json.dumps(data.get("scripts", {}), indent=2, sort_keys=True))
PY
fi
done
echo
echo "== FAQ relevant section =="
if [ -f FAQ.md ]; then
sed -n '130,155p' FAQ.md | awk '{printf "%4d %s\n", NR+129, $0}'
else
echo "FAQ.md not found"
fi
echo
echo "== root scripts using npm/npmx/concurrently =="
rg -n --hidden -S 'concurrently|npm run dev:backend|npm run dev:frontend|forever|pm2|nodemon|vite|dev' package.json backend/package.json frontend/package.json || trueRepository: ritik4ever/stellar-stream
Length of output: 1091
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== frontend package script =="
python3 - <<'PY'
import json
data=json.load(open('frontend/package.json', encoding='utf-8'))
print(json.dumps(data.get('scripts', {}), indent=2, sort_keys=True))
PY
echo
echo "== FAQ relevant section =="
sed -n '130,155p' FAQ.md | awk '{printf "%4d %s\n", NR+129, $0}'
echo
echo "== root scripts using npm/npmx/concurrently =="
rg -n --hidden -S 'concurrently|npm run dev:backend|npm run dev:frontend|forever|pm2|nodemon|vite|dev' package.json backend/package.json frontend/package.json || trueRepository: ritik4ever/stellar-stream
Length of output: 798
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
find . -maxdepth 3 -type f \( -path '*/FAQ.md' -o -path '*/package.json' -o -path '*/vite.config.*' -o -path '*/vite.config.ts' \) | sort
echo
echo "== frontend/package.json first lines =="
sed -n '1,120p' frontend/package.json 2>/dev/null || true
echo
echo "== FAQ relevant section =="
sed -n '130,155p' FAQ.md | awk '{printf "%4d %s\n", NR+129, $0}'
echo
echo "== frontend scripts from JSON-like extraction =="
python3 - <<'PY'
import json, re
from pathlib import Path
path=Path('frontend/package.json')
text=path.read_text(encoding='utf-8')
start=text.find('{')
end=text.rfind('}')
if start>=0 and end>start:
obj=json.loads(text[start:end+1])
print(json.dumps(obj.get('scripts', {}), indent=2, sort_keys=True))
PY
echo
echo "== root scripts hints =="
rg -n --hidden -S 'concurrently|npm run dev:backend|npm run dev:frontend|forever|pm2|nodemon|vite|vite|dev' package.json backend/package.json frontend/package.json 2>/dev/null || trueRepository: ritik4ever/stellar-stream
Length of output: 3244
Run the development servers in separate terminals.
npm run dev:backend starts ts-node-dev --respawn, which is a long-running process. The next command will not run in the same shell unless the first process exits, so document separate terminals or add a root script that starts both processes.
Proposed documentation change
- npm run dev:backend
- npm run dev:frontend
+# Run each command in a separate terminal.
+ npm run dev:backend
+ npm run dev:frontend📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Start frontend and backend in development mode | |
| npm run dev:backend | |
| npm run dev:frontend | |
| # Run each command in a separate terminal. | |
| npm run dev:backend | |
| npm run dev:frontend |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@FAQ.md` around lines 144 - 146, Update the development startup instructions
in FAQ.md to explicitly state that npm run dev:backend and npm run dev:frontend
must be run in separate terminals, since the backend command remains active. Do
not change the commands themselves.
Comment on lines
+207
to
+213
| ### How do I debug WebSocket/live-update issues? | ||
| The frontend uses polling (and WebSockets in newer flows) for near-real-time updates. If updates aren't appearing: | ||
| 1. Open Browser DevTools → **Network** tab. | ||
| 2. Filter by **WS** (WebSockets). | ||
| 3. Check if the connection to `ws://localhost:3001` is successful. | ||
| 4. Look for messages in the **Frames** or **Messages** sub-tab. | ||
| 5. Check [useWebSocket.ts](frontend/src/hooks/useWebSocket.ts) for reconnection logic. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the correct WebSocket endpoint.
The supplied WebSocket test connects to /api/ws, but Line 211 documents ws://localhost:3001 without that path. The backend also uses configured config.port, so 3001 is not universal. Document the configured backend URL with the /api/ws path.
Proposed documentation change
-3. Check if the connection to `ws://localhost:3001` is successful.
+3. Check if the connection to `ws://<backend-host>:<backend-port>/api/ws` is successful.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### How do I debug WebSocket/live-update issues? | |
| The frontend uses polling (and WebSockets in newer flows) for near-real-time updates. If updates aren't appearing: | |
| 1. Open Browser DevTools → **Network** tab. | |
| 2. Filter by **WS** (WebSockets). | |
| 3. Check if the connection to `ws://localhost:3001` is successful. | |
| 4. Look for messages in the **Frames** or **Messages** sub-tab. | |
| 5. Check [useWebSocket.ts](frontend/src/hooks/useWebSocket.ts) for reconnection logic. | |
| ### How do I debug WebSocket/live-update issues? | |
| The frontend uses polling (and WebSockets in newer flows) for near-real-time updates. If updates aren't appearing: | |
| 1. Open Browser DevTools → **Network** tab. | |
| 2. Filter by **WS** (WebSockets). | |
| 3. Check if the connection to `ws://<backend-host>:<backend-port>/api/ws` is successful. | |
| 4. Look for messages in the **Frames** or **Messages** sub-tab. | |
| 5. Check [useWebSocket.ts](frontend/src/hooks/useWebSocket.ts) for reconnection logic. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@FAQ.md` around lines 207 - 213, Update the WebSocket debugging instructions
to reference the configured backend URL using the configured port rather than
hardcoded 3001, and include the /api/ws path. Keep the surrounding DevTools and
reconnection guidance unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands FAQ.md from 10 to 32 Q&A entries, reorganized into the categories requested in the issue. Answers are grounded in the actual product behavior (stream math, indexer, webhooks, contract methods) as documented in README.md, RUNBOOK.md, SECURITY.md, docs/STREAM_MATH.md, and docs/USE_CASES.md, rather than generic filler content.
closes #793
Changes
Test plan
###heading and vice versa (32/32 match, no orphans) via a small script.No caveats — this is a docs-only change limited to FAQ.md.
Summary by CodeRabbit