feat: add stellar payment utilities for tip transactions

[Hallab7]

Description

Closes #247

This PR implements Stellar payment utilities to enable XLM tip transactions from viewers to creators on the StreamFi platform. It introduces a reusable, well-tested utility module for building and submitting Stellar payment transactions, which will be consumed by the tip modal feature.

Changes proposed

What were you told to do?

Create a utility module for building Stellar payment transactions using @stellar/stellar-sdk. The module should support constructing XLM tip transactions from viewers to creators, handle network selection, validate inputs, and provide proper error handling.

What did you do?

I implemented a complete Stellar payment utility with full TypeScript support and testing.

Files Created:

• lib/stellar/payments.ts

  • Added buildTipTransaction() to construct unsigned Stellar payment transactions
  • Added submitTransaction() to submit signed transactions to the Horizon API
  • Added getCurrentNetwork() to resolve testnet/mainnet from environment variables
  • Added isValidStellarPublicKey() for public key validation
  • Added formatXLMAmount() to format XLM amounts to 7 decimal places

• lib/stellar/__tests__/payments.test.ts

  • Added 8 comprehensive test cases covering exports, types, validation, formatting, network selection, transaction building, submission, and error handling

Files Modified:

• package-lock.json – Updated to properly install @stellar/stellar-sdk
• tsconfig.json – Minor configuration adjustment

Dependencies Installed:

• @stellar/stellar-sdk@^14.5.0
• ts-node@10.9.2 (dev dependency for running tests)

Key Features:

• Network selection (testnet/mainnet) via NEXT_PUBLIC_STELLAR_NETWORK
• Automatic memo inclusion: "StreamFi Tip"
• Robust error handling with user-friendly messages
• Full TypeScript typing for all parameters and return values
• Helper utilities for validation and formatting
• Verified end-to-end functionality on Stellar Testnet

Check List (Check all the applicable boxes)

🚨Please review the contribution guideline for this repository.

• My code follows the code style of this project.
• This PR does not contain plagiarized content.
• The title and description of the PR is clear and explains the approach.
• I am making a pull request against the main branch (left side).
• My commit messages styles matches our requested structure.
• My code additions will fail neither code linting checks nor unit test.
• I am only making changes to files I was requested to.

Screenshots/Videos

Test Results (Stellar Testnet)

• All unit tests passing
• Successful XLM payment transaction confirmed on Stellar Testnet
• Transaction memo, fee, timeout, and ledger recorded correctly

A video demo showing test execution, transaction submission, and Stellar Expert verification link in added below.

https://www.loom.com/share/12e1a92964a34674a543f2fda082613c

[vercel]

@Hallab7 is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.

[davedumto]

Great work on this PR! The implementation is excellent with comprehensive tests and documentation. 👏

However, I noticed a security concern:

Issue: Hardcoded Secret Key in Test File

In lib/stellar/tests/payments.test.ts:30, there's a hardcoded secret key:

sourceSecretKey: "SDTIZXLNUEXETRYIBQKYQ7MO3YXRKBPPTRJDZODQHZT57LZ7DBNENRTC", // Viewer secret

Even though this is a testnet key with no real value, it's bad practice to commit any secrets to the repository.

Recommended Fix

Update the test to load the secret from an environment variable and skip the transaction submission test if not provided:

const TEST_CONFIG = {
  sourcePublicKey: "GA5AJZ2HYSKNN5MGZGBBVCJ73RXOGXTWFV4FWCUDLVCJXKSLGTAI7L5F",
  sourceSecretKey: process.env.TEST_STELLAR_SECRET_KEY || "", // Load from env
  destinationPublicKey: "GD4KLYVQBT225M5UVGIKAQCHRI3YU2S7IOJG6B667ZVDTPGIXKJAOTQT",
  amount: "10.0000000",
  network: "testnet" as const,
};

// In Test 7, add a check:
if (\!TEST_CONFIG.sourceSecretKey) {
  console.log("   ⚠️  SKIPPED: Set TEST_STELLAR_SECRET_KEY env var to test submission");
} else {
  // ... existing submission test
}

Could you update this before we merge? Thanks!

[davedumto]

Merge Conflict Alert

This PR has merge conflicts that need to be resolved before merging.

Please pull the latest changes from dev and resolve the conflicts:

git checkout dev
git pull origin dev
# Resolve conflicts
git add .
git commit -m "fix: resolve merge conflicts with dev"
git push

Once conflicts are resolved, we can proceed with the merge after you address the hardcoded secret key issue mentioned above.

[Hallab7]

@davedumto secret key issue fixed and merge conflict resolved