🛒 Tefi.app — Digital Neighborhood Credit Ledger on Solana

Turning informal corner store credit ("el fiado") into a verifiable, portable on-chain repayment history, co-signed by store and neighbor.
Built for the Colosseum Crypto World's Fair Hackathon & Superteam Argentina Track.

• 🌐 Live Demo Web PWA: https://tef-iapp.vercel.app · en español: tef-iapp.vercel.app/es/
• 🎬 Product Demo Video (1:45): https://youtu.be/Q4kr51Gbqcc
• 🎤 Pitch Video (1:54): https://youtu.be/BY_HupD_pCE
• 📦 Solana Devnet Program: 9UmX9z1Cr2FCidUBgoMJzDCRp5aeTs7xz4umKRnEGnJQ
• 📝 What changed and when: CHANGELOG.md

---

📌 Problem & Local Insight

In Argentina and throughout Latin America, corner grocery stores (almacenes de barrio) sell on "el fiado": informal credit written in a paper notebook.

1. The Merchant's Dilemma: Merchants issue credit in Argentine Pesos and collect weeks later. In a high-inflation economy, delayed cash repayments erode the store's working capital.
2. The Neighbor's Invisibility: Customers repay their neighborhood debts faithfully for years, yet that repayment history is invisible to the formal financial system and cannot be shown to any lender.
3. The Core Insight: The corner store is already the neighborhood's first credit originator. What is missing is not credit itself, but a record of the repayment, signed by both parties, that the neighbor can take anywhere.

---

⚡ The Solution: Tefi.app

Tefi is a mobile-first Progressive Web App (PWA) that replaces the paper notebook with a ledger on Solana where every fiado and every repayment is a transaction signed by both the store and the neighbor, each from their own phone.

• 📱 One phone, one role, one key: On first use a phone is set up either as the Store (Almacén) or as a Neighbor (Vecino), gets the name its owner types and creates only that role's signing key.
• 🧾 Co-signed credit issuance: The merchant enters the amount in ARS (converted to USDC with the dolarapi.com exchange rate), takes a photo of the receipt and signs first. The request, carrying the store's signature, is shown as a QR code. The neighbor scans it with their own phone, reviews what the transaction says, adds the second signature and submits it.
• 🤝 Co-signed repayment: When the neighbor pays (cash or transfer, as today), the store confirms it by signing repay_fiado; the neighbor co-signs the same way. Neither party can record or settle a debt alone.
• ⛽ The neighbor needs no SOL: The store is the fee payer of every transaction and pays the rent of the accounts, including the neighbor's profile in their first fiado.
• 📈 Portable repayment history: Each on-time repayment raises the neighbor's on-chain score (+5) and credit limit (+5 USDC). Score, limit, debt and repaid total live in an account that any lender can read without asking Tefi.

Tefi records the debt and its repayment; the money itself keeps moving off-chain between neighbor and store. Amounts are stored in USDC units as a stable unit of account, not as token transfers.

---

🔏 How the Two-Phone Co-Signature Works

 STORE PHONE (holds only the store key)            NEIGHBOR PHONE (holds only the neighbor key)
 ──────────────────────────────────────            ────────────────────────────────────────────
                                                    0. Shows "My Tefi QR": public key and name only
 1. Scans it once: neighbor saved in the store's list
 2. Builds issue_fiado, feePayer = store
 3. tx.partialSign(storeKey)
 4. Shows a QR / link with its signature and
    the fields of the request  ─────────────────►  5. Rebuilds the same transaction with its own key
                                                    6. Verifies the store signature over it and rejects
                                                       anything that is not exactly a Tefi fiado/repayment
                                                       for its own key (no hidden instructions)
                                                    7. Checks that the receipt shown matches the
                                                       receipt_hash the store signed
                                                    8. tx.partialSign(neighborKey) and sends it
 9. Follows the transaction by its own signature
    and shows it on Solana Explorer  ◄───────────  9. Shows the transaction on Solana Explorer

• The only thing that travels between the phones is the content of the QR code. Implementation: src/solana/cosign.ts.
• A QR a phone camera can read. The QR does not carry the serialized transaction (about 830 characters, 97 modules per side) but the store's signature and the fields of the request (about 420 characters, 61 modules). Both phones build the message with the same fixed account order, so the neighbor's phone rebuilds byte for byte what the store signed, and any field altered on the way invalidates that signature. The serialized transaction remains as a fallback format. The in-app scanner decodes at the resolution of the camera, not of the viewfinder (src/services/qrDecoder.ts).
• A QR is valid for about a minute (Solana blockhash lifetime). The store phone re-signs it with a fresh blockhash before it expires. A signed request cannot be replayed: each fiado account is derived from a per-store nonce, and a settled fiado cannot be repaid again.
• Single-device demo: the role switch lets one browser act as both store and neighbor so the flow can be tried on a single device. In that case both keys live in the same browser and the app shows a permanent "Single-device demo: both keys are on this device" label. The transactions are still real two-signature transactions; what is lost is the separation between devices.

---

🛠️ Verified Tech Stack

Layer	Technology	Status & Purpose
Blockchain L1	Solana Devnet (api.devnet.solana.com, configurable)	Low fees and fast confirmation make co-signing a US$2–4 purchase at the counter viable.
Smart Contract	Anchor Framework (Rust) v0.29.0	PDAs for stores, neighbors and fiados. 14 integration tests against solana-test-validator in CI.
Web3 Client SDK	@solana/web3.js 1.x & @coral-xyz/anchor 0.29	Instruction building from the IDL, partial signing, transaction (de)serialization and account decoding.
Co-signature transport	qrcode & jsQR (plus the phone's own barcode detector where the browser has one)	The store's signature and the fields of the request travel from the store phone to the neighbor phone as a QR code or link.
Fee sponsorship	Store as fee payer	The store pays the network fee and account rent of every fiado and repayment, so neighbors never need SOL.
Frontend / PWA	React 18, TypeScript, Tailwind CSS, Vite	Mobile-first Progressive Web App (PWA) with precached assets.
Exchange rate	dolarapi.com REST API	Argentine Peso (ARS) to USD crypto rate, with a fixed reference rate as offline fallback. It is an off-chain REST feed, not an on-chain oracle.

Not part of this build (see the Roadmap below): attestations, embedded wallets, payment rails, insurance or savings products, on-chain price oracles and decentralized identity.

---

💡 Why Solana?

Daily grocery purchases of US$1.50 to US$10 (bread, milk, deli items) cannot carry a meaningful per-transaction cost:

• Low fees: Recording and co-signing a fiado costs a fraction of a cent in network fees, so the store can sponsor it.
• Fast confirmation: The fiado is confirmed while both people are still at the counter.
• Readable by anyone: The neighbor's history lives in program accounts that any lender or protocol can read over RPC, and it can later be exposed through a standard such as the Solana Attestation Service.

---

💼 Business Model (Hypothesis)

• Free for Corner Stores & Neighbors: The digital ledger is free for merchants and consumers.
• Who would pay: Lenders that already serve this segment (mutuals, credit cooperatives, microcredit fintechs) would pay an origination fee (1–2%) on loans granted to neighbors with a Tefi history, or a query fee (US$0.50–1.00) per verified history.

This is a hypothesis: it has not been validated with a paying lender yet. Validating it is one of the goals of the pilot.

---

🏛️ Smart Contract Architecture (Anchor)

The Anchor program (contracts/tefi_program/programs/tefi_program/src/lib.rs) enforces bilateral agreements through Program Derived Addresses (PDAs):

┌────────────────────────────────────────────────────────────────────────┐
│                          Solana Devnet State                           │
├────────────────────────────────┬───────────────────────────────────────┤
│ Merchant Profile PDA           │ Customer Profile PDA                  │
│ seeds = ["merchant", pubkey]   │ seeds = ["customer", pubkey]          │
│ • Business name & category     │ • On-chain Credit Score (0-100)       │
│ • Total sales & default stats  │ • Credit limit (USDC units)           │
│ • Sequential fiado nonce       │ • Active debt & total repaid          │
├────────────────────────────────┴───────────────────────────────────────┤
│ Fiado Record PDA                                                       │
│ seeds = ["fiado", merchant_pubkey, customer_pubkey, nonce]             │
│ • Amount (USDC units), due date, status (Active / Paid)                │
│ • receipt_hash: SHA-256 of the receipt, never the purchase details     │
└────────────────────────────────────────────────────────────────────────┘

Core Instructions

Instruction	Required signers	Who pays fee & rent	What it does
initialize_merchant	Store	Store	Creates the store profile PDA.
initialize_customer	Payer (store) + Neighbor	Store	Creates the neighbor profile PDA (score 65, limit 50 USDC). Sent in the same transaction as the neighbor's first fiado.
issue_fiado	Store + Neighbor	Store	Creates the fiado PDA and adds the debt, within the neighbor's on-chain limit. Rejects any receipt_hash that is not a 64-character hex SHA-256.
repay_fiado	Store + Neighbor	Store	Marks the fiado as paid. If repaid on or before the due date: score +5 (max 100) and limit +5 USDC.
claim_insurance	Store	Store	Program-level default marking after a mandatory 30-day grace period (lowers the neighbor's score). Not exposed in the PWA: there is no insurance fund.

🔗 Live Solana Devnet Transactions

The program is deployed on devnet under its own id. Open any link below and check the Signers of the transaction on Solana Explorer.

What	Where	What to look at
Program	9UmX9z1C…EGnJQ	Executable, owned by the upgradeable BPF loader.
Deployment (10 Oct 2026)	5AJEhGf3…XjuiR	The deployed bytes are the tefi_program-sbf artifact built by CI (282,728 bytes, SHA-256 d34303c5…6ca2e7).
Live Demo issue_fiado (2 devices in video)	2r5x9T9p…bGnn	Laptop store EUHTPsts… (fee payer) and phone neighbor 5DJf3uo3… (0 SOL). Receipt hash is SHA-256.
Live Demo repay_fiado (2 devices in video)	3aFeMRvV…vYjG	Co-signed repayment: store confirms received payment, neighbor score updates to 70 (Gold Tier), limit to 55 USDC.
Co-signed issue_fiado (automated e2e)	4niTarxJ…KYBzy	2 signatures: store E3MsTtDE… (fee payer) and neighbor 2j17nfLJ…. Instructions InitializeCustomer + .

How these transactions were produced. Two complementary verification suites:

1. Live physical two-device demo: a laptop (merchant Don Tito) and an independent smartphone (neighbor Mario) exchanging dynamic QR codes over camera, captured live in the demo video.
2. Automated end-to-end suite in e2e/two-phones-devnet.mjs on 10 Oct 2026: four isolated browser profiles driving the built PWA across two stores and two neighbors, verified directly on-chain after every step.

Reading that neighbor's history as a lender would (npm run read:history -- 2j17nfLJU1CETKKDvKpmJTxy43cnh3sNbRSFCE8GrCLE):

Credit score:   75 / 100
Credit limit:   60.00 USDC
Active debt:    0.00 USDC
Repaid to date: 2.44 USDC

Fiados co-signed with stores: 2
  PAID          0.94 USDC  due 2026-10-25  store E3MsTtDEG2v8V29Y7pfDbp66sSjJudVYZ7iKFjmbZVc5  account 22WAajsdMZu7AfrUhPGeTuP6dE8M7oaqApah8h5XZcak
  PAID          1.50 USDC  due 2026-10-25  store HXU7bxpntV9KtziSmtKJbaiqkzBiGSmoGNin8yoCjeJY  account DNSSGwp7i4d7rMmQ2UqZpUjSziaiaT39UpukCxVv6sX7

The 06/10 deployment (3bs3SLqe…) is superseded: it does not include the bilateral repay_fiado and cannot be upgraded.

🔍 How Any Third-Party Lender Reads a Neighbor's History On-Chain

A lender only needs the neighbor's public key and an RPC endpoint. No Tefi server is involved:

import { Connection, PublicKey } from '@solana/web3.js';
import { BorshAccountsCoder, Idl } from '@coral-xyz/anchor';
import idl from './src/solana/idl.json';

const PROGRAM_ID = new PublicKey('9UmX9z1Cr2FCidUBgoMJzDCRp5aeTs7xz4umKRnEGnJQ');
const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
const coder = new BorshAccountsCoder(idl as Idl);

const neighbor = new PublicKey('<neighbor public key>');
const [profilePda] = PublicKey.findProgramAddressSync([Buffer.from('customer'), neighbor.toBuffer()], PROGRAM_ID);

// Credit profile: one account per neighbor
const profile = coder.decode('CustomerProfile', (await connection.getAccountInfo(profilePda))!.data);
console.log('Credit score:', profile.creditScore); // 0-100
console.log('Credit limit (USDC):', profile.creditLimitUsdc.toNumber() / 1_000_000);
console.log('Active debt (USDC):', profile.activeDebtUsdc.toNumber() / 1_000_000);
console.log('Repaid to date (USDC):', profile.totalRepaidUsdc.toNumber() / 1_000_000);

// Every fiado of that neighbor, across all stores (customer is at byte offset 40 of FiadoRecord)
const fiados = await connection.getProgramAccounts(PROGRAM_ID, {
  filters: [{ memcmp: { offset: 40, bytes: neighbor.toBase58() } }]
});
for (const { account } of fiados) {
  const fiado = coder.decode('FiadoRecord', account.data);
  console.log(fiado.merchant.toBase58(), fiado.amountUsdc.toNumber() / 1_000_000, fiado.status === 2 ? 'PAID' : 'ACTIVE');
}

The same read is available as a script: npm run read:history -- <neighbor public key> (scripts/read-neighbor-history.mjs).

---

🔒 Privacy, Security & Known Risks

• On-chain: pseudonymous public keys, amounts, due dates, status and the SHA-256 of each receipt. The store's business name is public in its profile.
• Only on the phones: the neighbor's name, the purchase details and the receipt photo. The program rejects readable ASCII text in receipt_hash.
• What the neighbor signs is what the transaction says: the neighbor's phone decodes the transaction, shows its amount and due date, and refuses anything other than a Tefi fiado or repayment addressed to its own key.
• Audit status: The Anchor smart contract is a hackathon prototype deployed on Solana Devnet. It has not undergone a third-party professional security audit. It is strictly intended for demonstration and devnet testing, not for handling real mainnet funds.
• Known design limits & attack vectors:
  • Devnet key storage: Signing keys are generated in the browser and kept in localStorage without account recovery. Clearing browser storage loses the key. Embedded wallets (e.g., Privy/Turnkey) and social recovery are planned for the production roadmap before any pilot with real funds.
  • Score farming without store identity (G-1): Anyone can initialize a merchant account (InitializeMerchant is permissionless). In the prototype, small repeated self-transactions (1 micro-USDC) could technically increment a customer's score. Production mitigation requires merchant whitelisting, physical verification, or volume/reputation weighting.
  • Merchant signature dependency for repayment (G-2): Repayment requires the store's signature to confirm receipt of cash. If a store refuses to sign a completed repayment, after due date + 30 days the store could theoretically trigger an insurance claim. Bilateral escrow, cryptographic payment receipts, and SAS dispute mechanisms are part of the production roadmap.
  • Receipt privacy (G-5): receipt_hash is a SHA-256 hash without salt; the purchase line items travel off-chain in the QR code or direct messaging link.

---

📊 Field Validation in Mar del Plata

• 4 Corner Store Interviews conducted across working-class neighborhoods in Mar del Plata, Argentina.
• 2 Stores actively confirmed to participate in the upcoming 30-day pilot trial.
• Key Learning: Average grocery ticket is $2.00 - $4.00 USD (bread, milk, deli items) settled on weekly wage days. Stores in the interview sample rely entirely on physical paper notebooks with zero inflation hedge and zero credit portability for neighbors.
• Business Model Note: The proposed origination/query fee structure is an early design hypothesis to be tested and validated during the 30-day merchant trial.

---

🧪 Tests

Command	What it runs	Tests
npm test	Vitest suites that import the real modules: the co-signature protocol (cosign.test.ts), instruction building and account decoding (program.test.ts), RPC error classification (anchorClient.test.ts), request pacing under the RPC rate limit (rpcRetry.test.ts), QR decoding at camera resolution (qrDecoder.test.ts), the debt ledger (financialLedger.test.ts), the passbook view (libreta.test.ts), Spanish/English completeness (translations.test.ts), the version label (version.test.ts) and what the site publishes for search engines and AI assistants (site.test.ts).	107
anchor test (CI)	Mocha tests against the compiled program on solana-test-validator: both signatures required, credit limit, double repayment, unauthorized store, grace period, hashed receipts and a two-device partial-signing round trip with a 0 SOL neighbor ().

All four run in GitHub Actions on every pull request and on every push to main: .github/workflows/anchor.yml (PWA build, npm test and the site check against the built PWA) and .github/workflows/contract-ci.yml (SBF build, Anchor tests and then the end-to-end run, with the PWA pointed at the same local validator). To run the end-to-end test against devnet yourself:

npm run build && npx vite preview --port 4173 &   # serve the built PWA
npm install --prefix e2e                           # Playwright driver + QR decoder; drives your installed Chrome
npm run e2e:devnet -- <keypair.json holding ~0.1 devnet SOL>

It funds two throwaway store wallets from that keypair (0.03 SOL each) and writes screenshots and a report.json with every transaction to e2e/shots/. Set TEFI_BROWSER_CHANNEL=msedge to drive Edge instead of Chrome.

---

🔎 Version on Every Screen, Link Previews & Crawlers

• Which version is this phone running? Every screen shows a line like Version 2.1.0 · 687581d · 2026-10-10 13:28: the version of package.json, the commit the app was built from (the line links to that commit on GitHub) and the date of that commit in the phone's own time. The same data is published at /version.json. Two phones run the same build only if they show the same line; a phone showing an older one has to reopen the app (src/version.ts).
• Spanish at its own address. /es/ opens the app in Spanish for a first-time visitor and has its link preview in Spanish; the root address is the English one. A language chosen with the flags wins over the address.
• Link previews. Sharing either address on WhatsApp, X, LinkedIn or Slack shows a title, a description and a 1200x630 image in that language (Open Graph and Twitter tags). The images are drawn by scripts/make-og-images.mjs.
• What a crawler gets without running JavaScript. Most AI assistants and several search engines do not run it, and a React app is an empty page to them. Each language page carries a description, canonical and hreflang links, schema.org WebApplication data and, inside <noscript>, the text of what Tefi is, how it works and where the code and the on-chain program are. The site also publishes robots.txt, sitemap.xml and llms.txt. All of it is generated at build time from src/site/; nothing is hand-written into dist.

---

🗺️ Roadmap

The app only shows what runs on-chain today. Everything below is not built yet:

• Core MVP (live on Devnet): two-phone co-signed credit issuance and repayment with the store as fee payer, hashed receipts, on-chain score and limit, passbook read from chain, full English & Spanish UI (flag switch).
• 30-day pilot with the committed stores, measuring fiados recorded and on-time repayment rate.
• Solana Attestation Service (SAS): a standard attestation per on-time repayment, readable by lenders that do not know the Tefi program.
• Embedded wallets: keys out of browser storage and account recovery before any pilot with real neighbors.
• Solana Actions & Blinks: repayment links over WhatsApp.
• Mutual guarantee fund for stores, only together with a regulated partner.

---

🚀 Getting Started Locally

Prerequisites

• Node.js 20+ & npm
• Modern web browser with camera access (for the QR flows)

Installation

# Clone the repository
git clone https://github.com/devOr05/tefi-app.git
cd tefi-app

# Install dependencies
npm install

# Start development server
npm run dev

# Run the tests
npm test

Try the flow

1. Store phone: open the app, choose I'm the store, type the name of the store and request devnet SOL (the +1 SOL button, or faucet.solana.com with the store address).
2. Neighbor phone: open the app, choose I'm a neighbor, type your name and tap My Tefi QR.
3. Store phone: Neighbors → Add and scan the neighbor's QR. Then Credit: amount, items, photo, Sign & Show QR to the Neighbor.
4. Neighbor phone: Scan QR, review and Sign & accept fiado. Both phones link to the transaction on Solana Explorer.
5. Repayment: on the store phone tap Register payment on the fiado and let the neighbor scan the new QR.

With a single device, use the Store / Neighbor switch in the header: the app labels it as a single-device demo.

Production Build

npm run build

Public address

The pages declare the address they are published at (canonical link, sitemap, link previews). It defaults to https://tef-iapp.vercel.app; to publish under another domain, build with VITE_SITE_URL=https://<your domain>.

RPC endpoint

The app talks to the public devnet node, which accepts roughly 40 requests per 10 seconds per IP address (measured on 10 Oct 2026). Every phone behind the same Wi-Fi shares that budget, and rejected requests count against it too. When the node answers 429, the app repeats the request and spaces out all the requests of that phone until the node accepts them again (src/solana/rpcRetry.ts), so a busy network shows up as a few seconds of waiting.

For an event with many phones on one network, point the build at your own devnet endpoint:

VITE_SOLANA_DEVNET_RPC_URL=https://<your devnet rpc> npm run build

Deploying the program

The program id is declared in lib.rs, Anchor.toml, src/solana/idl.json and src/solana/program.ts (CI and npm test check that they match). The SBF binary is built by the Anchor Contract Compilation & Localnet Tests workflow and published as the tefi_program-sbf artifact.

solana program deploy tefi_program.so --program-id <program keypair or id> --keypair <upgrade authority keypair> --url devnet

Keep the upgrade authority keypair outside the repository.

---

👥 Team & Attributions

• Mario Orostizaga — Founder & Full-Stack Developer

  • Location: Mar del Plata, Argentina
  • GitHub: @devOr05
  • LinkedIn: Mario Orostizaga
  • Focus: Grassroots merchant interviews, smart contracts, and mobile retail UX.

• Technical Collaboration & Attributions

  • Fran Camet (@FranCamet) — External Technical Collaborator
    • Contributions: Fran contributed significantly as a technical collaborator: deploying the Anchor program to Solana Devnet (9UmX9z1C…), implementing the real two-phone cryptographic co-signing flow (store as fee payer, zero SOL needed for neighbors), building the Vitest test suite and automated Devnet E2E checks, and cleaning up mocked modules to strictly reflect verified on-chain functionality.
  • AI-Assisted Development — Built with the assistance of Anthropic Claude (Opus 5 / Claude 3.5 Sonnet) and Google Gemini for iterative pair-programming, test suite expansion (Vitest & Anchor), and documentation verification.