docs: add ADR for Soroban contract integration approach

[ZuLu0890]

• Add docs/adr/0002-soroban-integration.md documenting the decision to use backend-signed transactions
• Cover server-side signing vs client-side Freighter signing trade-offs
• Explain STELLAR_SECRET_KEY server keypair pattern and security considerations
• Document hybrid approach (server creates, client claims)
• Update CONTRIBUTING.md to link to the new ADR

Closes #428

Generated with Devin

What changed

Testing done

Related issues

Closes #

Checklist

• I kept the change focused on the related issue.
• I added or updated tests where useful.
• I updated documentation where behavior changed.
• I verified the app still builds or explained why verification was skipped.
  closes Write ADR for Soroban contract integration approach #428

Summary by CodeRabbit

• Documentation
  • Contributing guidelines expanded with a new Architecture Decision Records section, providing centralized references to important design decisions, technical strategies, and documentation
  • New architecture decision document published detailing technical implementation approaches, required system configuration, environment variables, security considerations, and alternative implementation strategies that were evaluated
  • Instructions for contract event snapshot testing clarified and improved

[vercel]

Someone is attempting to deploy a commit to the ritik4ever's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds architectural documentation for Soroban smart contract integration. It introduces ADR 0002 that specifies a backend-signed transaction strategy where the server signs and submits stream creation transactions using a keypair from SERVER_PRIVATE_KEY, while claim recording is stored locally in the database. The PR also updates CONTRIBUTING.md to reference the new ADR and adjusts snapshot testing instructions.

Changes

Soroban Integration ADR and Documentation

Layer / File(s)	Summary
ADR decision and server-side signing architecture docs/adr/0002-soroban-integration.md	ADR 0002 status and decision statement establish backend-signed transaction approach; server-side signing implementation uses SERVER_PRIVATE_KEY keypair to prepare, sign, and submit transactions with retry logic.
Hybrid model flow and security trade-offs docs/adr/0002-soroban-integration.md	Rationale compares server-side signing versus client-side Freighter wallet signing, enumerates security and operational trade-offs, and specifies hybrid architecture where server creates streams while claim endpoint records claims locally.
Configuration, environment setup, and security docs/adr/0002-soroban-integration.md	SERVER_PRIVATE_KEY format, required environment variables (contract ID, RPC URL, network passphrase), security best practices, and SOROBAN_DISABLED development toggle to run without valid Soroban infrastructure.
Consequences, mitigations, and alternatives docs/adr/0002-soroban-integration.md	Positive and negative consequences including key management, monitoring, rate limiting, and validation; mitigation strategies; rejected alternatives of pure client-side signing and multi-signature approaches.
References and contributing guide integration docs/adr/0002-soroban-integration.md, CONTRIBUTING.md	References to backend stream creation, environment validation, and claim endpoints; Stellar SDK and Soroban documentation links; CONTRIBUTING.md adds Architecture Decision Records section and updates snapshot testing instructions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• ritik4ever/stellar-stream#287: Both PRs modify CONTRIBUTING.md's Soroban-related contributor documentation, specifically snapshot testing instructions.

Poem

🐰 A rabbit hops through docs so bright,
ADRs penned with care and might,
Soroban flows from server's key,
Streams shall flow, both sure and free! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding an ADR document for Soroban contract integration approach.
Linked Issues check	✅ Passed	The PR fully addresses all acceptance criteria from issue #428: documents backend-signed vs client-side trade-offs, explains STELLAR_SECRET_KEY pattern, covers the hybrid approach, and links from CONTRIBUTING.md.
Out of Scope Changes check	✅ Passed	All changes are directly related to issue #428: the ADR document creation and CONTRIBUTING.md update to link it. No unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch adr/soroban-integration-approach

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[drips-wave]

@ZuLu0890 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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/adr/0002-soroban-integration.md`:
- Around line 112-115: The section heading "STELLAR_SECRET_KEY Server Keypair
Pattern" is inconsistent with the implemented and documented env variable
`SERVER_PRIVATE_KEY`; update the heading and any nearby references and examples
to use `SERVER_PRIVATE_KEY` (or vice versa if you intend to change the
implementation) so the title, prose, and code examples all match
`SERVER_PRIVATE_KEY`, and verify the README/docs don't contain leftover
`STELLAR_SECRET_KEY` mentions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d78d632-4463-4d50-bb55-8ec49a6d8625

📥 Commits

Reviewing files that changed from the base of the PR and between 3e86821 and 7d8fd04.

📒 Files selected for processing (2)

• CONTRIBUTING.md
• docs/adr/0002-soroban-integration.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix env var naming inconsistency in the keypair section.

The section title says STELLAR_SECRET_KEY, but the documented and implemented variable is SERVER_PRIVATE_KEY. This can cause misconfiguration during setup.

Suggested doc fix

-### STELLAR_SECRET_KEY Server Keypair Pattern
+### SERVER_PRIVATE_KEY Server Keypair Pattern

📝 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

	### STELLAR_SECRET_KEY Server Keypair Pattern
	The `SERVER_PRIVATE_KEY` environment variable follows a specific pattern:
	### SERVER_PRIVATE_KEY Server Keypair Pattern
	The `SERVER_PRIVATE_KEY` environment variable follows a specific pattern:

🤖 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 `@docs/adr/0002-soroban-integration.md` around lines 112 - 115, The section
heading "STELLAR_SECRET_KEY Server Keypair Pattern" is inconsistent with the
implemented and documented env variable `SERVER_PRIVATE_KEY`; update the heading
and any nearby references and examples to use `SERVER_PRIVATE_KEY` (or vice
versa if you intend to change the implementation) so the title, prose, and code
examples all match `SERVER_PRIVATE_KEY`, and verify the README/docs don't
contain leftover `STELLAR_SECRET_KEY` mentions.