Skip to content

Commit deaf14f

Browse files
davidleomaydavidleomay
authored
Merge pull request #86 from LightningDotSpace/develop
Dev to Main
2 parents f4811cc + 01b8eb7 commit deaf14f

58 files changed

Lines changed: 3167 additions & 149 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,13 @@ SQL_DB=
88
SQL_SYNCHRONIZE=
99
SQL_MIGRATE=
1010
JWT_SECRET=
11-
DISABLED_PROCESSES=
11+
DISABLED_PROCESSES=
12+
13+
# Debug endpoint (scripts/db-debug.sh, scripts/log-debug.sh)
14+
DEBUG_ADDRESS=
15+
DEBUG_SIGNATURE=
16+
DEBUG_API_URL=
17+
18+
# Azure Application Insights (for log-debug.sh)
19+
AZURE_APP_INSIGHTS_APP_ID=
20+
AZURE_APP_INSIGHTS_API_KEY=

‎README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,85 @@
11
# lightning.space API
22

33
API for lightning.space custodial service
4+
5+
Do not merge this state into PRD!
6+
7+
## Debug Endpoint
8+
9+
The API provides a debug endpoint for authorized users to execute read-only SQL queries and access Azure Application Insights logs.
10+
11+
### Endpoints
12+
13+
| Endpoint | Method | Description |
14+
|----------|--------|-------------|
15+
| `/support/debug` | POST | Execute SQL SELECT queries |
16+
| `/support/debug/logs` | POST | Query Azure Application Insights |
17+
18+
### Authorization
19+
20+
Access requires a wallet with the `DEBUG` role. The role hierarchy allows `ADMIN` users to also access debug endpoints.
21+
22+
### Getting Access
23+
24+
1. **Generate wallet credentials** from a mnemonic seed:
25+
```bash
26+
node -e "
27+
const { ethers } = require('ethers');
28+
const mnemonic = '<your-12-word-seed>';
29+
const wallet = ethers.Wallet.fromMnemonic(mnemonic);
30+
const message = 'By_signing_this_message,_you_confirm_to_lightning.space_that_you_are_the_sole_owner_of_the_provided_Blockchain_address._Your_ID:_' + wallet.address;
31+
console.log('Address:', wallet.address);
32+
wallet.signMessage(message).then(sig => console.log('Signature:', sig));
33+
"
34+
```
35+
36+
2. **Register the wallet** on the target environment (dev/prd) via the normal registration flow.
37+
38+
3. **Create a migration** to grant DEBUG role (replace `TIMESTAMP` with `date +%s000`):
39+
```javascript
40+
// migration/TIMESTAMP-addDebugWallet.js
41+
const { MigrationInterface, QueryRunner } = require("typeorm");
42+
43+
module.exports = class addDebugWalletTIMESTAMP {
44+
name = 'addDebugWalletTIMESTAMP'
45+
46+
async up(queryRunner) {
47+
await queryRunner.query(`UPDATE wallet SET role = 'Debug', updated = GETDATE() WHERE address = 'WALLET_ADDRESS'`);
48+
}
49+
50+
async down(queryRunner) {
51+
await queryRunner.query(`UPDATE wallet SET role = 'User', updated = GETDATE() WHERE address = 'WALLET_ADDRESS'`);
52+
}
53+
}
54+
```
55+
56+
4. **Configure environment** - create `.env` in the api root:
57+
```
58+
DEBUG_ADDRESS=<wallet-address>
59+
DEBUG_SIGNATURE=<signature>
60+
DEBUG_API_URL=https://lightning.space/v1 # or https://dev.lightning.space/v1
61+
```
62+
63+
### Usage
64+
65+
**SQL Queries:**
66+
```bash
67+
./scripts/db-debug.sh "SELECT TOP 10 * FROM wallet"
68+
./scripts/db-debug.sh "SELECT * FROM monitoring_balance"
69+
```
70+
71+
**Log Queries:**
72+
```bash
73+
./scripts/log-debug.sh exceptions # Recent exceptions
74+
./scripts/log-debug.sh failures # Failed requests
75+
./scripts/log-debug.sh slow 2000 # Slow dependencies (>2000ms)
76+
./scripts/log-debug.sh traces "error" # Search traces
77+
./scripts/log-debug.sh operation <guid> # Traces by operation ID
78+
```
79+
80+
### Security
81+
82+
- Only `SELECT` queries allowed (no INSERT, UPDATE, DELETE)
83+
- Sensitive columns are automatically masked (signatures, keys, secrets)
84+
- System schemas blocked (sys, information_schema)
85+
- All queries are logged for audit

‎docs/CROSS_CHAIN_BRIDGING.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Cross-Chain Bridging & Arbitrage
2+
3+
**How JUSD maintains its peg through cross-chain infrastructure connecting Ethereum, Citrea, and Lightning Network.**
4+
5+
## Overview
6+
7+
JuiceDollar (JUSD) on Citrea is connected to other networks through multiple bridging mechanisms. This enables:
8+
9+
1. **Price stability** through arbitrage opportunities
10+
2. **Liquidity access** to major stablecoin markets
11+
3. **Fast settlements** via Lightning Network
12+
13+
The combination of Layer0 cross-chain messaging and Lightning.space atomic swaps creates a complete arbitrage loop that helps maintain the JUSD peg.
14+
15+
## Bridge Architecture
16+
17+
```
18+
ETHEREUM CITREA
19+
┌──────────────────┐ ┌───────────────────────┐
20+
│ │ │ │
21+
│ USDT │───Layer0────▶│ USDT.e │
22+
│ 0xdAC17F958... │ │ 0x9f3096Bac... │
23+
│ │ │ │ │
24+
└────────▲─────────┘ │ ▼ │
25+
│ │ StablecoinBridge │
26+
│ │ │ │
27+
│ │ ▼ │
28+
│ Lightning.space │ JUSD │
29+
└─────────────────────────│ │
30+
(Atomic Swap) └───────────────────────┘
31+
```
32+
33+
## Layer0 (LayerZero) Bridges
34+
35+
LayerZero provides omnichain messaging to bridge assets between Ethereum and Citrea.
36+
37+
### Ethereum → Citrea Bridges
38+
39+
| Asset | Ethereum Contract | Citrea Contract | Type |
40+
|-------|-------------------|-----------------|------|
41+
| **USDT** | [`0x6925ccD29e3993c82a574CED4372d8737C6dbba6`](https://etherscan.io/address/0x6925ccD29e3993c82a574CED4372d8737C6dbba6) | [`0x9f3096Bac87e7F03DC09b0B416eB0DF837304dc4`](https://explorer.mainnet.citrea.xyz/address/0x9f3096Bac87e7F03DC09b0B416eB0DF837304dc4) | SourceOFTAdapter → USDT.e |
42+
| **USDC** | [`0xdaa289CC487Cf95Ba99Db62f791c7E2d2a4b868E`](https://etherscan.io/address/0xdaa289CC487Cf95Ba99Db62f791c7E2d2a4b868E) | [`0xE045e6c36cF77FAA2CfB54466D71A3aEF7bBE839`](https://explorer.mainnet.citrea.xyz/address/0xE045e6c36cF77FAA2CfB54466D71A3aEF7bBE839) | SourceOFTAdapter → USDC.e |
43+
| **WBTC** | [`0x2c01390E10e44C968B73A7BcFF7E4b4F50ba76Ed`](https://etherscan.io/address/0x2c01390E10e44C968B73A7BcFF7E4b4F50ba76Ed) | [`0xDF240DC08B0FdaD1d93b74d5048871232f6BEA3d`](https://explorer.mainnet.citrea.xyz/address/0xDF240DC08B0FdaD1d93b74d5048871232f6BEA3d) | WBTCOFTAdapter → WBTC.e |
44+
45+
### Bridge Contracts on Citrea
46+
47+
| Contract | Address | Purpose |
48+
|----------|---------|---------|
49+
| USDC.e Token | [`0xE045e6c36cF77FAA2CfB54466D71A3aEF7bBE839`](https://explorer.mainnet.citrea.xyz/address/0xE045e6c36cF77FAA2CfB54466D71A3aEF7bBE839) | Bridged USDC from Ethereum |
50+
| USDC.e Bridge | [`0x41710804caB0974638E1504DB723D7bddec22e30`](https://explorer.mainnet.citrea.xyz/address/0x41710804caB0974638E1504DB723D7bddec22e30) | DestinationOUSDC |
51+
| USDT.e Token | [`0x9f3096Bac87e7F03DC09b0B416eB0DF837304dc4`](https://explorer.mainnet.citrea.xyz/address/0x9f3096Bac87e7F03DC09b0B416eB0DF837304dc4) | Bridged USDT from Ethereum |
52+
| USDT.e Bridge | [`0xF8b5983BFa11dc763184c96065D508AE1502C030`](https://explorer.mainnet.citrea.xyz/address/0xF8b5983BFa11dc763184c96065D508AE1502C030) | DestinationOUSDT |
53+
| WBTC.e + Bridge | [`0xDF240DC08B0FdaD1d93b74d5048871232f6BEA3d`](https://explorer.mainnet.citrea.xyz/address/0xDF240DC08B0FdaD1d93b74d5048871232f6BEA3d) | WBTCOFT (combined) |
54+
55+
### Source Token Verification
56+
57+
All bridges use the **official Ethereum token contracts**:
58+
59+
| Token | Ethereum Address | Decimals |
60+
|-------|------------------|----------|
61+
| USDT (Tether) | [`0xdAC17F958D2ee523a2206206994597C13D831ec7`](https://etherscan.io/address/0xdAC17F958D2ee523a2206206994597C13D831ec7) | 6 |
62+
| USDC (Circle) | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) | 6 |
63+
| WBTC | [`0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599`](https://etherscan.io/address/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599) | 8 |
64+
65+
## Lightning.space Swaps
66+
67+
Lightning.space provides atomic swaps between Ethereum stablecoins and JUSD on Citrea via the Lightning Network.
68+
69+
### Swap Pairs
70+
71+
All stablecoin swaps are exclusively against **JUSD** (JuiceDollar) on Citrea.
72+
73+
#### USDT Pairs
74+
75+
| From | To | Direction | Min | Max |
76+
|------|-----|-----------|-----|-----|
77+
| ETH USDT | JUSD | Chain Swap | 1 USDT | 10,000 USDT |
78+
| JUSD | ETH USDT | Reverse Swap | 1 USDT | 10,000 USDT |
79+
| Polygon USDT | JUSD | Chain Swap | 1 USDT | 10,000 USDT |
80+
| JUSD | Polygon USDT | Reverse Swap | 1 USDT | 10,000 USDT |
81+
82+
#### USDC Pairs (Ethereum only)
83+
84+
| From | To | Direction | Min | Max |
85+
|------|-----|-----------|-----|-----|
86+
| ETH USDC | JUSD | Chain Swap | 1 USDC | 10,000 USDC |
87+
| JUSD | ETH USDC | Reverse Swap | 1 USDC | 10,000 USDC |
88+
89+
> **Note:** Polygon USDC is not supported due to bridge incompatibility (native USDC vs bridged USDC.e).
90+
91+
### Contract Addresses
92+
93+
#### Ethereum Mainnet
94+
95+
| Contract | Address |
96+
|----------|---------|
97+
| EtherSwap | [`0x9ADfB0F1B783486289Fc23f3A3Ad2927cebb17e4`](https://etherscan.io/address/0x9ADfB0F1B783486289Fc23f3A3Ad2927cebb17e4) |
98+
| ERC20Swap | [`0x2E21F58Da58c391F110467c7484EdfA849C1CB9B`](https://etherscan.io/address/0x2E21F58Da58c391F110467c7484EdfA849C1CB9B) |
99+
| USDT Token | [`0xdAC17F958D2ee523a2206206994597C13D831ec7`](https://etherscan.io/address/0xdAC17F958D2ee523a2206206994597C13D831ec7) |
100+
| USDC Token | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) |
101+
102+
#### Polygon Mainnet
103+
104+
| Contract | Address |
105+
|----------|---------|
106+
| EtherSwap | [`0x9ADfB0F1B783486289Fc23f3A3Ad2927cebb17e4`](https://polygonscan.com/address/0x9ADfB0F1B783486289Fc23f3A3Ad2927cebb17e4) |
107+
| ERC20Swap | [`0x2E21F58Da58c391F110467c7484EdfA849C1CB9B`](https://polygonscan.com/address/0x2E21F58Da58c391F110467c7484EdfA849C1CB9B) |
108+
| USDT Token | [`0xc2132D05D31c914a87C6611C10748AEb04B58e8F`](https://polygonscan.com/address/0xc2132D05D31c914a87C6611C10748AEb04B58e8F) |
109+
110+
#### Citrea Mainnet
111+
112+
| Contract | Address |
113+
|----------|---------|
114+
| EtherSwap | [`0xd02731fD8c5FDD53B613A699234FAd5EE8851B65`](https://explorer.mainnet.citrea.xyz/address/0xd02731fD8c5FDD53B613A699234FAd5EE8851B65) |
115+
| ERC20Swap | [`0xf2e019a371e5Fd32dB2fC564Ad9eAE9E433133cc`](https://explorer.mainnet.citrea.xyz/address/0xf2e019a371e5Fd32dB2fC564Ad9eAE9E433133cc) |
116+
| JUSD | [`0xFdB0a83d94CD65151148a131167Eb499Cb85d015`](https://explorer.mainnet.citrea.xyz/address/0xFdB0a83d94CD65151148a131167Eb499Cb85d015) |
117+
118+
### Token Compatibility
119+
120+
Lightning.space uses the **same Ethereum token contracts** as Layer0:
121+
122+
```
123+
Ethereum USDT: 0xdAC17F958D2ee523a2206206994597C13D831ec7
124+
Ethereum USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
125+
```
126+
127+
This ensures that tokens bridged via Layer0 can be used in Lightning.space swaps and vice versa.
128+
129+
## StablecoinBridge: USDT.e → JUSD
130+
131+
A StablecoinBridge contract can connect Layer0's USDT.e to JUSD on Citrea.
132+
133+
### How It Works
134+
135+
```solidity
136+
// Deposit USDT.e, receive JUSD (1:1)
137+
function mint(uint256 amount) external
138+
139+
// Burn JUSD, receive USDT.e (1:1)
140+
function burn(uint256 amount) external
141+
```
142+
143+
The bridge automatically handles decimal conversion:
144+
- USDT.e: 6 decimals
145+
- JUSD: 18 decimals
146+
147+
### Planned Deployment
148+
149+
| Parameter | Value |
150+
|-----------|-------|
151+
| Source Token | USDT.e (`0x9f3096Bac87e7F03DC09b0B416eB0DF837304dc4`) |
152+
| Target Token | JUSD |
153+
| Exchange Rate | 1:1 |
154+
| Network | Citrea Mainnet |
155+
156+
## The Arbitrage Loop
157+
158+
With all components in place, arbitrageurs can close the loop:
159+
160+
### Loop 1: JUSD → ETH USDT → USDT.e → JUSD
161+
162+
```
163+
Step 1: Burn JUSD via StablecoinBridge
164+
→ Receive USDT.e on Citrea
165+
166+
Step 2: Bridge USDT.e to Ethereum via Layer0
167+
→ Receive USDT on Ethereum
168+
169+
Step 3: Swap USDT to JUSD via Lightning.space
170+
→ Receive JUSD on Citrea
171+
```
172+
173+
### Loop 2: JUSD → ETH USDT via Lightning → USDT.e → JUSD
174+
175+
```
176+
Step 1: Swap JUSD to USDT via Lightning.space
177+
→ Receive USDT on Ethereum
178+
179+
Step 2: Bridge USDT to Citrea via Layer0
180+
→ Receive USDT.e on Citrea
181+
182+
Step 3: Mint JUSD via StablecoinBridge
183+
→ Receive JUSD on Citrea
184+
```
185+
186+
### Economic Implications
187+
188+
| Scenario | Arbitrage Action | Effect on JUSD |
189+
|----------|------------------|----------------|
190+
| JUSD > $1 | Mint JUSD from USDT.e, sell for profit | Increases supply, price decreases |
191+
| JUSD < $1 | Buy cheap JUSD, burn for USDT.e | Decreases supply, price increases |
192+
193+
This creates a self-correcting mechanism that maintains the JUSD peg.
194+
195+
## Fee Structure
196+
197+
### Layer0 Bridge Fees
198+
199+
- Gas fees on source chain (Ethereum)
200+
- LayerZero messaging fees
201+
- Gas fees on destination chain (Citrea)
202+
203+
### Lightning.space Swap Fees
204+
205+
| Swap Type | Fee |
206+
|-----------|-----|
207+
| All Swaps | 0% |
208+
209+
### StablecoinBridge Fees
210+
211+
- **No protocol fees** for mint/burn
212+
- Only gas costs on Citrea (paid in cBTC)
213+
214+
## Security Considerations
215+
216+
### Bridge Risks
217+
218+
| Risk | Mitigation |
219+
|------|------------|
220+
| Layer0 bridge exploit | Multiple security audits, decentralized validation |
221+
| Lightning.space failure | Non-custodial atomic swaps, timeout refunds |
222+
| StablecoinBridge exploit | Volume limits, time-based expiration, emergency stop |
223+
| USDT depeg | Volume limits, governance veto power |
224+
225+
### Best Practices
226+
227+
1. **Verify contract addresses** before large transactions
228+
2. **Check bridge liquidity** on both sides
229+
3. **Monitor gas costs** - arbitrage must exceed fees
230+
4. **Use official frontends** to avoid phishing
231+
232+
## API Endpoints
233+
234+
### Lightning.space
235+
236+
| Environment | Base URL |
237+
|-------------|----------|
238+
| Production | `https://lightning.space/v1/swap/` |
239+
| Development | `https://dev.lightning.space/v1/swap/` |
240+
241+
### Citrea RPC
242+
243+
| Environment | RPC URL |
244+
|-------------|---------|
245+
| Mainnet | `https://rpc.citrea.xyz` |
246+
| Testnet | `https://rpc.testnet.citrea.xyz` |
247+
248+
## Summary
249+
250+
The cross-chain infrastructure enables:
251+
252+
1. **Ethereum ↔ Citrea** via Layer0 (USDT, USDC, WBTC)
253+
2. **Ethereum ↔ Citrea JUSD** via Lightning.space (atomic swaps)
254+
3. **USDT.e ↔ JUSD** via StablecoinBridge (on-chain, 1:1)
255+
256+
Together, these create a robust arbitrage mechanism that keeps JUSD pegged to $1.
257+
258+
### Component Status
259+
260+
| Component | Status | Contract Verified |
261+
|-----------|--------|-------------------|
262+
| Layer0 USDT Bridge | Live | Yes |
263+
| Layer0 USDC Bridge | Live | Yes |
264+
| Layer0 WBTC Bridge | Live | Yes |
265+
| Lightning.space Swaps | Live | Yes |
266+
| StablecoinBridge (USDT.e) | Planned | - |

0 commit comments

Comments
 (0)