toncast-swap-proxy

Proxy contract on TON blockchain that receives TON from STON.fi DEX swaps and forwards them to the TonCast Pari contract.

Architecture

User Wallet
  │  jetton_transfer (USDT / TCAST / any jetton)
  ▼
STON.fi DEX v2+ (swap → TON)
  │  pTON ton_transfer (0x01f3835d) + forward_payload
  ▼
Proxy Contract
  │  parses forward_payload:
  │    opcode 0x50415249 → pariAddress + Pari payload cell
  │  validates cost against msg_value
  │    ok  → forwards exact totalCost to Pari, returns change
  │    low → refunds to refund_address
  ▼
Pari Contract

Two modes of operation

Mode	Opcode	Source	Refund on error
Wrapped	0x01f3835d (pTON ton_transfer)	DEX swap output	refund_address from wrapper
Direct	0x50415249 ("PARI")	Direct TON transfer	sender_address

Any other opcode or empty body → fallback address.

Payload format

forward_payload (opcode 0x50415249):
  ├── pariAddress: Address
  └── ref: Pari payload cell
            ├── opcode: uint32 (0xaabbccef or 0xaabbccf0)
            ├── beneficiary: Address
            ├── isYes: Bool
            ├── entries: Dict<uint8, ref {yesOdds: uint7, ticketsCount: uint32}>
            └── [referral: Address?, referralPct: uint3]  (0xaabbccf0 only)

Cost validation

The proxy calculates the required amount using the same formula as the Pari contract:

per entry: PARI_EXECUTION_FEE + ticketCost × ticketsCount
  where ticketCost = WIN_AMOUNT_PER_TICKET × odds / 100

Forward happens only when msg_value >= totalCost + CONTRACT_RESERVE.

TON flow on success

1. Pari receives exactly totalCost (forward fee paid from contract balance)
2. Change (msg_value - totalCost - CONTRACT_RESERVE) returned to refund address
3. CONTRACT_RESERVE (0.01 TON) stays on proxy for storage fees

Refund strategy

Scenario	Destination	Keeps 0.01 TON
Wrapper parse error / unknown opcode	Fallback address	Yes
Valid wrapper, invalid forward opcode	refund_address	Yes
Valid wrapper, invalid Pari payload	refund_address	Yes
Direct mode, parse error	Fallback address	Yes
Insufficient TON for cost	refund_address / sender	Yes
Bounced from Pari	Fallback address	Yes
Forward success	Pari + change to refund	Yes

Deployed contract

• Address: EQCiRGAqGbzlWVq8Ryu-uTW88MMi_u5CfhRmrR0hHtf41lvl
• Code hash: ed127401a02e22de56e609622ba4dba0f130d5b757a4cca8911c5cc5e4fb8fcb

Project structure

• contracts/ — Tolk 1.3 smart contract source
• wrappers/ — TypeScript wrapper with payload builders
• tests/ — sandbox tests (12 cases)
• scripts/ — deploy deeplink generator
• swap-test/ — STON.fi swap + TonKeeper deeplink generator

Build

npx blueprint build

Test

npx blueprint test

Deploy

npx tsx scripts/deployDeeplink.ts

Generates a TonKeeper deeplink for signing the deploy transaction.

License

MIT