Back to Details

starknet-mini-pay

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Starknet Mini-Pay Skill

Starknet Mini-Pay 工具

Simple P2P payments on Starknet. Like Lightning, but native.
Starknet上的简易P2P支付工具。类Lightning网络，但为原生实现。

Overview

概述

┌─────────────────────────────────────────────────────────┐
│                    STARKNET MINI-PAY                    │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │  QR Codes   │  │  Payment    │  │   Telegram Bot  │ │
│  │  Generator  │  │   Links     │  │   Interface     │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│           │                │                   │          │
│           └────────────────┴───────────────────┘          │
│                         │                                │
│              ┌─────────▼─────────┐                       │
│              │   starknet-py    │                       │
│              │   SDK + RPC      │                       │
│              └──────────────────┘                       │
│                         │                                │
│         ┌───────────────┼───────────────┐               │
│         ▼               ▼               ▼               │
│    ┌─────────┐    ┌──────────┐    ┌──────────┐         │
│    │ ArgentX │    │  Braavos │    │  Generic  │         │
│    │ Account │    │ Account  │    │  Account  │         │
│    └─────────┘    └──────────┘    └──────────┘         │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│                    STARKNET MINI-PAY                    │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │  QR Codes   │  │  Payment    │  │   Telegram Bot  │ │
│  │  Generator  │  │   Links     │  │   Interface     │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│           │                │                   │          │
│           └────────────────┴───────────────────┘          │
│                         │                                │
│              ┌─────────▼─────────┐                       │
│              │   starknet-py    │                       │
│              │   SDK + RPC      │                       │
│              └──────────────────┘                       │
│                         │                                │
│         ┌───────────────┼───────────────┐               │
│         ▼               ▼               ▼               │
│    ┌─────────┐    ┌──────────┐    ┌──────────┐         │
│    │ ArgentX │    │  Braavos │    │  Generic  │         │
│    │ Account │    │ Account  │    │  Account  │         │
│    └─────────┘    └──────────┘    └──────────┘         │
└─────────────────────────────────────────────────────────┘

Features

功能特性

FeatureDescription
P2P TransfersSend ETH/STRK/USDC to any Starknet address
QR CodesGenerate QR codes for addresses (scan to pay)
Payment Links
starknet:<addr>?amount=1&memo=coffee
Invoice SystemGenerate payment requests with expiry
Telegram BotSend/receive via Telegram commands
Transaction HistoryTrack all transfers with status
功能描述
P2P转账向任意Starknet地址转账ETH/STRK/USDC
二维码生成为地址生成支付二维码（扫码即可付款）
支付链接格式示例：
starknet:<addr>?amount=1&memo=coffee
发票系统生成带过期时间的付款请求
Telegram机器人通过Telegram指令收发款项
交易历史追踪所有转账及状态

Quick Start

快速开始

CLI Usage

CLI 使用方法

bash
undefined
bash
undefined

Send payment

发起支付

python3.12 scripts/cli.py send 0x123... 0.5 --memo "coffee"
python3.12 scripts/cli.py send 0x123... 0.5 --memo "coffee"

Generate QR code for your address

为你的地址生成二维码

python3.12 scripts/cli.py qr 0x123... --output qr.png
python3.12 scripts/cli.py qr 0x123... --output qr.png

Create payment link

创建支付链接

python3.12 scripts/cli.py link 0x123... --amount 0.1 --memo "lunch"
python3.12 scripts/cli.py link 0x123... --amount 0.1 --memo "lunch"

Create invoice

创建发票

python3.12 scripts/cli.py invoice 0x123... 25.00 --expires 1h
python3.12 scripts/cli.py invoice 0x123... 25.00 --expires 1h

Check transaction status

检查交易状态

python3.12 scripts/cli.py status 0xabcdef...
python3.12 scripts/cli.py status 0xabcdef...

Balance check

查询余额

python3.12 scripts/cli.py balance 0x123...
undefined
python3.12 scripts/cli.py balance 0x123...
undefined

Payment Link Format

支付链接格式

starknet:<address>?amount=<value>&memo=<text>&token=<ETH|STRK|USDC>
Example:
starknet:0x053c91253bc9682c04929ca02ed00b3e423f6714d2ea42d73d1b8f3f8d400005?amount=0.01&memo=coffee&token=ETH
starknet:<address>?amount=<value>&memo=<text>&token=<ETH|STRK|USDC>
示例：
starknet:0x053c91253bc9682c04929ca02ed00b3e423f6714d2ea42d73d1b8f3f8d400005?amount=0.01&memo=coffee&token=ETH

Telegram Bot Commands

Telegram机器人指令

/pay <address> <amount> [memo]  - Send payment
/qr                          - Show your QR code
/balance                     - Check balance
/link <amount> [memo]       - Generate payment link
/invoice <amount>           - Create invoice
/history                     - Transaction history
/help                        - Show help
/pay <address> <amount> [memo]  - 发起支付
/qr                          - 展示你的二维码
/balance                     - 查询余额
/link <amount> [memo]       - 生成支付链接
/invoice <amount>           - 创建发票
/history                     - 交易历史
/help                        - 展示帮助信息

Architecture

项目架构

starknet-mini-pay/
├── SKILL.md
├── README.md
├── scripts/
│   ├── cli.py              # Main CLI interface
│   ├── mini_pay.py         # Core payment logic
│   ├── qr_generator.py     # QR code generation
│   ├── link_builder.py     # Payment link builder
│   ├── invoice.py          # Invoice system
│   ├── telegram_bot.py     # Telegram bot
│   └── starknet_client.py  # Starknet RPC client
├── contracts/
│   └── payment_request.cairo  # Optional invoice contract
└── tests/
    └── test_payments.py
starknet-mini-pay/
├── SKILL.md
├── README.md
├── scripts/
│   ├── cli.py              # 主CLI交互入口
│   ├── mini_pay.py         # 核心支付逻辑
│   ├── qr_generator.py     # 二维码生成模块
│   ├── link_builder.py     # 支付链接构建模块
│   ├── invoice.py          # 发票系统模块
│   ├── telegram_bot.py     # Telegram机器人模块
│   └── starknet_client.py  # Starknet RPC客户端
├── contracts/
│   └── payment_request.cairo  # 可选发票合约
└── tests/
    └── test_payments.py

Dependencies

依赖安装

bash
pip install starknet-py --break-system-packages
pip install qrcode[pil] --break-system-packages
pip install python-telegram-bot --break-system-packages
pip install httpx aiosqlite --break-system-packages
bash
pip install starknet-py --break-system-packages
pip install qrcode[pil] --break-system-packages
pip install python-telegram-bot --break-system-packages
pip install httpx aiosqlite --break-system-packages

Configuration

配置说明

bash
undefined
bash
undefined

Environment variables

环境变量配置

export STARKNET_RPC="https://rpc.starknet.lava.build:443" export MINI_PAY_PRIVATE_KEY="0x..." export MINI_PAY_ADDRESS="0x..." export TELEGRAM_BOT_TOKEN="..." export TELEGRAM_CHAT_ID="..."
undefined
export STARKNET_RPC="https://rpc.starknet.lava.build:443" export MINI_PAY_PRIVATE_KEY="0x..." export MINI_PAY_ADDRESS="0x..." export TELEGRAM_BOT_TOKEN="..." export TELEGRAM_CHAT_ID="..."
undefined

Core Functions

核心功能示例

Send Payment

发起支付

python
from mini_pay import MiniPay

pay = MiniPay(rpc_url="https://rpc.starknet.lava.build:443")
python
from mini_pay import MiniPay

pay = MiniPay(rpc_url="https://rpc.starknet.lava.build:443")

Send ETH

转账ETH

tx_hash = pay.send( from_address="0x...", private_key="0x...", to_address="0x123...", amount_wei=0.5 * 10**18, token="ETH" )
tx_hash = pay.send( from_address="0x...", private_key="0x...", to_address="0x123...", amount_wei=0.5 * 10**18, token="ETH" )

Check status

检查交易状态

status = pay.get_status(tx_hash) print(f"Status: {status}") # PENDING, CONFIRMED, FAILED
undefined
status = pay.get_status(tx_hash) print(f"状态: {status}") # PENDING, CONFIRMED, FAILED
undefined

Generate QR Code

生成二维码

python
from qr_generator import QRGenerator

qr = QRGenerator()
qr.generate(
    address="0x053c91253bc9682c04929ca02ed00b3e423f6714d2ea42d73d1b8f3f8d400005",
    amount=None,  # Optional amount
    memo=None,     # Optional memo
    output_file="address_qr.png"
)
python
from qr_generator import QRGenerator

qr = QRGenerator()
qr.generate(
    address="0x053c91253bc9682c04929ca02ed00b3e423f6714d2ea42d73d1b8f3f8d400005",
    amount=None,  # 可选金额
    memo=None,     # 可选备注
    output_file="address_qr.png"
)

Payment Links

支付链接

python
from link_builder import PaymentLink

link = PaymentLink()
python
from link_builder import PaymentLink

link = PaymentLink()

Create link

创建支付链接

url = link.create( address="0x123...", amount=0.01, memo="coffee", token="ETH" )
url = link.create( address="0x123...", amount=0.01, memo="coffee", token="ETH" )

Parse incoming link

解析传入的支付链接

data = link.parse("starknet:0x123...?amount=0.01&memo=coffee")
undefined
data = link.parse("starknet:0x123...?amount=0.01&memo=coffee")
undefined

Invoice System

发票系统

python
from invoice import InvoiceManager

invoice = InvoiceManager()
python
from invoice import InvoiceManager

invoice = InvoiceManager()

Create invoice

创建发票

invoice_data = invoice.create( payer_address="0x...", amount=25.00, token="USDC", expiry_seconds=3600, # 1 hour description="Payment for services" )
invoice_data = invoice.create( payer_address="0x...", amount=25.00, token="USDC", expiry_seconds=3600, # 1小时 description="服务费用付款" )

Check invoice status

检查发票状态

status = invoice.get_status(invoice_data.id)
undefined
status = invoice.get_status(invoice_data.id)
undefined

Telegram Bot

Telegram机器人

Run Bot

启动机器人

bash
python3.12 scripts/telegram_bot.py
bash
python3.12 scripts/telegram_bot.py

Bot Flow

机器人交互流程

User: /pay 0x123... 0.5 coffee
Bot:  📤 Sending 0.5 ETH to 0x123... (memo: coffee)
Bot:  ⏳ Transaction pending: 0xabc...
Bot:  ✅ Confirmed in block #12345
用户: /pay 0x123... 0.5 coffee
机器人:  📤 正在向0x123...转账0.5 ETH（备注: coffee）
机器人:  ⏳ 交易待确认: 0xabc...
机器人:  ✅ 已在区块#12345中确认

Optional: Invoice Contract

可选功能：发票合约

For trustless invoices, deploy the Cairo contract:
cairo
// contracts/payment_request.cairo

#[starknet::contract]
mod PaymentRequest {
    #[storage]
    struct Storage {
        request_id: u256,
        requests: Map<u256, Request>,
        owner: ContractAddress,
    }

    #[derive(Drop, Serde)]
    struct Request {
        amount: u256,
        token: ContractAddress,
        recipient: ContractAddress,
        expiry: u64,
        fulfilled: bool,
        memo: felt252,
    }

    #[external(v0)]
    impl IPaymentRequestImpl of IPaymentRequest<ContractState> {
        fn create_request(
            ref self: ContractState,
            amount: u256,
            token: ContractAddress,
            expiry: u64,
            memo: felt252
        ) -> u256 {
            // Create payment request
        }

        fn fulfill_request(
            ref self: ContractState,
            request_id: u256
        ) {
            // Execute payment
        }
    }
}
如需无信任发票功能，可部署以下Cairo合约：
cairo
// contracts/payment_request.cairo

#[starknet::contract]
mod PaymentRequest {
    #[storage]
    struct Storage {
        request_id: u256,
        requests: Map<u256, Request>,
        owner: ContractAddress,
    }

    #[derive(Drop, Serde)]
    struct Request {
        amount: u256,
        token: ContractAddress,
        recipient: ContractAddress,
        expiry: u64,
        fulfilled: bool,
        memo: felt252,
    }

    #[external(v0)]
    impl IPaymentRequestImpl of IPaymentRequest<ContractState> {
        fn create_request(
            ref self: ContractState,
            amount: u256,
            token: ContractAddress,
            expiry: u64,
            memo: felt252
        ) -> u256 {
            // 创建付款请求
        }

        fn fulfill_request(
            ref self: ContractState,
            request_id: u256
        ) {
            // 执行付款
        }
    }
}

Error Handling

错误处理

ErrorCauseSolution
INSUFFICIENT_BALANCE
Not enough ETH for transferAdd more ETH to account
ACCOUNT_NOT_FOUND
Invalid sender addressCheck address format
INVALID_AMOUNT
Amount <= 0Use positive amount
TX_FAILED
Transaction revertedCheck recipient address
INVOICE_EXPIRED
Invoice past expiryCreate new invoice
错误类型原因解决方案
INSUFFICIENT_BALANCE
账户余额不足向账户充值更多ETH
ACCOUNT_NOT_FOUND
发送方地址无效检查地址格式
INVALID_AMOUNT
金额小于等于0使用正数金额
TX_FAILED
交易被回滚检查接收方地址
INVOICE_EXPIRED
发票已过期创建新发票

Payment Flow

支付流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Sender    │     │  Mini-Pay   │     │  Recipient  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  1. Initiate      │                   │
       │──────────────────▶│                   │
       │                   │                   │
       │                   │  2. Execute      │
       │                   │  ETH Transfer    │
       │                   │─────────────────▶
       │                   │                   │
       │                   │  3. Confirm      │
       │                   │◀──────────────────
       │  4. Success       │                   │
       │◀──────────────────│                   │
       │                   │                   │
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   付款方    │     │  Mini-Pay   │     │   收款方    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  1. 发起付款请求   │                   │
       │──────────────────▶│                   │
       │                   │                   │
       │                   │  2. 执行ETH转账   │
       │                   │─────────────────▶
       │                   │                   │
       │                   │  3. 确认交易完成   │
       │                   │◀──────────────────
       │  4. 收到成功通知   │                   │
       │◀──────────────────│                   │
       │                   │                   │

Security Notes

安全注意事项

  • Private keys: Never expose in logs or error messages
  • Amount validation: Prevent negative/zero amounts
  • Expiry checks: Invoices expire automatically
  • Address format: Validate Starknet addresses (0x... format)
  • 私钥安全: 切勿在日志或错误信息中暴露私钥
  • 金额验证: 禁止负数或零金额交易
  • 过期检查: 发票会自动过期
  • 地址校验: 验证Starknet地址格式（需以0x开头）

Comparison with Lightning

与Lightning网络对比

FeatureLightningStarknet Mini-Pay
Setup timeHours (channels)Instant
PrivacyOnion routingNative (per txn)
Speed~1 sec~2-3 min
FeesVariablePredictable
CustodyLightning nodeSelf-custody
NativeNo (needs BTC)Yes (Starknet native)
特性LightningStarknet Mini-Pay
部署时间数小时（需创建通道）即时
隐私性洋葱路由原生（每笔交易独立）
速度~1秒~2-3分钟
手续费可变可预测
托管方式Lightning节点托管自托管
原生支持否（依赖BTC）是（Starknet原生）

Roadmap

开发路线图

  • Multi-token support (STRK, USDC, DAI)
  • Batch payments
  • Payment requests via IPFS
  • Web interface
  • Mobile app (Flutter)
  • MPC wallet integration
  • 多代币支持（STRK, USDC, DAI）
  • 批量付款
  • 基于IPFS的付款请求
  • Web界面
  • 移动端应用（Flutter）
  • MPC钱包集成

Resources

相关资源