Freighter Wallet Integration (Stellar Only)

[kelly-musk]

Label: wallet | stellar | integration
Priority: High
Estimated Time: 6-8 hours
Value: $150 USDC

---

📋 Overview

Implement Freighter wallet as the single wallet solution for AFRAMP. Stellar network only, no EVM chains, no multi-wallet complexity.

Live Site: https://aframp.vercel.app/

---

💡 Why Freighter Only?

• ✅ Most popular Stellar wallet (90%+ users)
• ✅ Simple UX - one clear choice
• ✅ Mobile app available
• ✅ Perfect for cNGN/African stablecoins
• ✅ Faster to build and maintain

---

🎯 What to Build

1. Connect Button (Header)

Not connected: [Connect Freighter]
Connected: GAXYZ...ABC123 [▼]
  ├─ Copy Address
  ├─ View on Explorer  
  └─ Disconnect

2. Connection Modal

If Freighter not installed:

• Show install guide
• Link to Chrome Web Store
• Link to mobile app
• Step-by-step instructions

If requesting connection:

• "Waiting for Freighter approval..."
• What AFRAMP can/cannot do
• Security messaging

If wrong network:

• Detect testnet vs mainnet
• Guide to switch networks
• Refresh button

3. Auto-Reconnect

• Save connection to localStorage
• Auto-reconnect on page load
• Silent if previously connected
• Clear if Freighter disconnected

4. Balance Fetching

• Fetch XLM + all assets (cNGN, USDC, etc.)
• Update every 30 seconds
• Show in wallet dropdown
• Handle unfunded accounts

5. Transaction Signing

• Open Freighter popup
• Sign transactions
• Handle approval/rejection
• Return transaction hash

---

📦 Core Files

src/
  lib/wallet/
    freighter.ts           # SDK wrapper
    walletStore.ts         # State management
    
  components/Wallet/
    ConnectButton.tsx      # Main button
    WalletModal.tsx        # Modals
    WalletDropdown.tsx     # Connected dropdown
    
  hooks/
    useWallet.ts           # Main hook

---

✅ Acceptance Criteria

Connection:

• Detects if Freighter installed
• Shows install modal if not
• Connects on button click
• Saves to localStorage
• Auto-reconnects on refresh

Network:

• Detects mainnet/testnet
• Shows warning if wrong network
• Provides switch instructions

Balances:

• Fetches all asset balances
• Updates every 30 seconds
• Handles unfunded accounts

Transactions:

• Signs transactions via Freighter
• Handles user approval
• Handles user rejection
• Returns transaction hash

UI/UX:

• Mobile responsive
• Works on Freighter mobile app
• All errors handled gracefully
• Loading states everywhere
• Clean, professional design

Code:

• TypeScript (no any)
• No console errors
• Works in Chrome, Firefox, Edge
• Documented

---

🚀 Implementation Steps

Phase 1 (3-4 hours):

1. Install @stellar/freighter-api
2. Create wallet store (Zustand)
3. Build connect button
4. Implement connection logic
5. Add localStorage persistence

Phase 2 (2-3 hours):
6. Build connection modals
7. Add balance fetching
8. Create wallet dropdown
9. Implement disconnect

Phase 3 (1-2 hours):
10. Error handling
11. Testing (desktop + mobile)
12. Documentation

---

📚 Resources

• [Freighter Docs](https://docs.freighter.app/)
• [Stellar SDK](https://stellar.github.io/js-stellar-sdk/)
• [Freighter Chrome Store](https://chrome.google.com/webstore/detail/freighter/bcacfldlkkdogcmkkibnjlakofdplcbk)

---

🎯 Success

Complete when:

1. ✅ One-click connection works
2. ✅ Auto-reconnect works
3. ✅ Balances display correctly
4. ✅ Transaction signing works
5. ✅ Mobile works (Freighter app)
6. ✅ All errors handled

Quality: Rock-solid. This is the foundation for everything.

---

Ready? Comment "Taking this" with your completion date! 🚀

[Michaelkingsdev]

Hello @kelly-musk
I can perfectly handle this issue but its not showing on drips

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[Luluameh]

@Luluameh has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

HI
I will love to work on this .
please kindle assign me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Luluameh to this issue.

[JoyLight00]

@JoyLight00 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Let me handle this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @JoyLight00 to this issue.

[Obiajulu-gif]

@Obiajulu-gif has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Can I work on this issue?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Obiajulu-gif to this issue.

[SimpleX-T]

@SimpleX-T has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi,

I want to resolve this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @SimpleX-T to this issue.

[Georgechisom]

@Georgechisom has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi, I love to work on this issue, pleas help assign it to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Georgechisom to this issue.

[Benalex8797]

@Benalex8797 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

hi, please i will love to solve this issue. kindly assign to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Benalex8797 to this issue.

[jahrulezfrancis]

@jahrulezfrancis has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Taking this.
I’ll implement Freighter as the sole wallet (Stellar-only) per spec: connect flow, install/network modals, auto-reconnect, balance polling, transaction signing, and full error handling. Clean TypeScript, Zustand store, mobile-ready, and documented.

ETA: 6–8 hours

ℹ️ Repo Maintainers: To accept this application, review their application or assign @jahrulezfrancis to this issue.

[Sam-Rytech]

@Sam-Rytech has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to claim this issue. I have experience implementing Stellar wallet connections using @stellar/freighter-api and managing complex async state with Zustand.

will ensure the implementation covers the full lifecycle—including robust auto-reconnect logic, network mismatch detection, and graceful handling of unfunded accounts—while verifying full functionality within the Freighter mobile app browser.

I can deliver this within 6-8 hour.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Sam-Rytech to this issue.

[caxtonacollins]

@caxtonacollins has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

i will love to work on this
ETA 2hrs

ℹ️ Repo Maintainers: To accept this application, review their application or assign @caxtonacollins to this issue.

[Benjtalkshow]

@Benjtalkshow has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I am a Full Stack Developer specializing in Next.js, TypeScript, Node.js, Cairo and Rust . With over 120 contributions across projects in web3 and specifically stellar ecosystem, I’ve developed strong proficiency in delivering high-quality solutions and resolving complex issues within tight deadlines. My experience spans frontend, backend, smart contracts, and the optimization and maintenance of scalable codebases.
I can handle this task. Kindly assign.

Here are my wallet implementation proofs:

MesaChain/MesaChain#89
Stellar-Rent/stellar-rent#93
Stellar-Rent/stellar-rent#109
PayStell/paystell-website#128
Crypto-Jaguars/Revo-Marketplace#91
PayStell/paystell-backend#112

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Benjtalkshow to this issue.

[Benjtalkshow]

@Benjtalkshow has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I am a Full Stack Developer specializing in Next.js, TypeScript, Node.js, Cairo and Rust . With over 120 contributions across projects in web3 and specifically stellar ecosystem, I’ve developed strong proficiency in delivering high-quality solutions and resolving complex issues within tight deadlines. My experience spans frontend, backend, smart contracts, and the optimization and maintenance of scalable codebases.
I can handle this task. Kindly assign.

Here are my wallet implementation proofs:

MesaChain/MesaChain#89
Stellar-Rent/stellar-rent#93
Stellar-Rent/stellar-rent#109
PayStell/paystell-website#128
Crypto-Jaguars/Revo-Marketplace#91
PayStell/paystell-backend#112

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Benjtalkshow to this issue.

[Michaelkingsdev]

@Michaelkingsdev has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I am Michael Kings, a seasoned full-stack developer with extensive experience in blockchain technology. I have a passion for building responsive and interactive user interfaces, and my backend logic is top-notch. With 4 years of experience, I am confident that I can tackle this issue. I have made over 50 contributions in onlydust in the past.
Please assign it to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Michaelkingsdev to this issue.