Dora Milen

Posted on Sep 18

TON Coin za developere: kako mreža zaista funkcioniše

#blockchain #cryptocurrency #web3 #bitcoin

TON se često predstavlja kroz brzinu transakcija, Telegram integraciju i niske naknade. To jesu važne karakteristike, ali developeru ne objašnjavaju kako da napravi pouzdanu aplikaciju.

Pravo pitanje nije koliko transakcija mreža teoretski može da obradi, već kako se na TON-u modeluju stanje, izvršavanje i komunikacija između smart contracta.

Ako dolazite iz Ethereum ekosistema, najveća greška je da TON posmatrate kao EVM blockchain sa drugačijim adresama i jeftinijim gasom. TON nije EVM kompatibilna mreža, smart contracti ne koriste Solidity ABI, a složena operacija preko više contracta nije jedna velika sinhrona transakcija.

TON je distribuirani sistem u kojem nalozi razmenjuju asinhrone poruke. Ta odluka utiče na gotovo sve:

način projektovanja smart contracta
obradu grešaka i povratnih poruka
praćenje uplata
strukturu tokena
testiranje
backend arhitekturu
korisničko iskustvo

Tek kada se prihvati ovaj model, cells, Bag of Cells, traceovi, jetton walleti i bounce poruke prestaju da deluju kao nepovezane specifičnosti mreže.

TON, TON Coin i Gram nisu ista stvar

Pre tehničkih detalja treba razjasniti terminologiju.

TON, odnosno The Open Network, naziv je blockchain mreže.

Izvorna valuta mreže dugo je bila poznata kao Toncoin, TON Coin ili jednostavno TON. Aktuelni naziv valute je Gram, sa oznakom GRAM. Promena se odnosi na naziv, ticker i vizuelni identitet valute, ne na novu mrežu ili novi token koji bi korisnici morali da zamene.

Zbog kompatibilnosti, veliki deo postojećeg koda i dalje koristi stare tehničke nazive. U SDK-ovima ćete zato sretati:

toNano
nanoTON
AssetType.ton
pakete sa prefiksom @ton
polja, metode i komentare koji pominju TON kao valutu

To ne znači da koristite zastareli blockchain. Tehnički identifikatori ne menjaju se nužno istom brzin om kao naziv prikazan u walletu.

U nastavku teksta izraz TON Coin povremeno koristim kao prepoznatljiv naziv teme, dok se Gram odnosi na aktuelni naziv izvorne valute. U kodu treba pratiti konkretan SDK i njegove stvarne nazive, a ne ručno preimenovati metode koje još uvek koriste ton ili nanoTon.

Jedan GRAM deli se na milijardu najmanjih jedinica. Iznosi se zato čuvaju kao celi brojevi, ne kao floating-point vrednosti.

type GramAmount = bigint;

const oneGram: GramAmount = 1_000_000_000n;
const halfGram: GramAmount = 500_000_000n;

U JavaScriptu i TypeScriptu za blockchain iznose treba koristiti bigint ili decimalne stringove. Izraz poput 0.1 + 0.2 nije prihvatljiva osnova za finansijsku evidenciju.

Šta je TON iz ugla developera

TON je Layer 1 blockchain projektovan za horizontalno skaliranje. Smart contracti čuvaju stanje i izvršavaju kod u TON Virtual Machine okruženju, ali međusobno ne komuniciraju kao objekti unutar jednog procesa.

Oni razmenjuju poruke.

TON arhitektura može se posmatrati kroz tri nivoa:

masterchain
workchain
shardchain

Masterchain čuva globalnu konfiguraciju mreže, informacije potrebne za rad validatora, sistemske contracte i reference na poslednja prihvaćena stanja shardchainova.

Workchain predstavlja blockchain sa sopstvenim pravilima, formatima naloga i adresnim prostorom. Većina korisničkih naloga i aplikacionih contracta nalazi se u basechainu, čiji je workchain_id jednak 0.

Masterchain koristi workchain_id jednak -1.

Shardchainovi su delovi workchaina koji se obrađuju paralelno. Workchain može biti podeljen na više shardova kada opterećenje poraste, a shardovi se mogu ponovo spojiti kada dodatni kapacitet nije potreban.

Iz ugla aplikacije, račun ili smart contract pripada određenom workchainu i shardu. Kako se topologija shardova menja, contract ne dobija novu adresu niti aplikacija treba ručno da ga migrira.

Ovakva arhitektura omogućava mreži da raspodeli stanje i izvršavanje. Istovremeno, ona nameće pravilo da komunikacija između naloga mora biti asinhrona.

Contract A ne može pretpostaviti da će contract B završiti posao pre nego što se nastavi izvršavanje contracta A. Contract A može poslati poruku i završiti svoju transakciju. Contract B tu poruku obrađuje u posebnoj transakciji.

To je bliže actor modelu i distribuiranim servisima nego klasičnom pozivu funkcije.

Zašto je actor model važniji od brzine mreže

Zamislimo escrow aplikaciju.

Korisnik šalje sredstva escrow contractu. Escrow zatim treba da obavesti marketplace contract, koji proverava narudžbinu i šalje potvrdu. Nakon toga escrow oslobađa sredstva prodavcu.

Na sinhronom sistemu developer bi mogao da zamisli jednu operaciju:

escrow.deposit()
marketplace.confirm()
escrow.release()

Na TON-u se ovaj proces sastoji od više transakcija:

Wallet šalje internu poruku escrow contractu.
Escrow obrađuje poruku i menja svoje lokalno stanje.
Escrow šalje poruku marketplace contractu.
Marketplace obrađuje poruku.
Marketplace šalje potvrdu escrow contractu.
Escrow obrađuje potvrdu i šalje sredstva prodavcu.
Wallet prodavca prima transfer.

Sve ove transakcije zajedno čine širi tok koji se često posmatra kao trace.

Drugi korisnici i contracti mogu izvršavati sopstvene transakcije između pojedinih koraka. Zato escrow ne sme da pretpostavi da je njegovo stanje ostalo nepromenjeno dok je čekao odgovor.

Pouzdana implementacija bi čuvala nešto poput:

order_id
buyer
seller
amount
status
created_at
confirmation_deadline

Status bi mogao prolaziti kroz stanja:

created
funded
confirmation_pending
release_pending
released
refund_pending
refunded

Svaka primljena poruka mora proveriti da li je zahtev dozvoljen u trenutnom stanju.

Ovo je osnovni obrazac TON programiranja: smart contract je state machine, a poruke su događaji koji pokreću prelaze između stanja.

Nalog i smart contract su deo istog modela

Na TON-u svaki nalog ima adresu, balans i status. Aktivan nalog može imati kod i persistentne podatke, što ga čini smart contractom.

Tokom životnog ciklusa nalog može biti u jednom od četiri stanja:

nonexist
uninit
active
frozen

nonexist znači da nalog ne postoji u aktivnom stanju blockchaina. Nema balans, kod ni persistentne podatke.

uninit znači da adresa ima balans, ali smart contract još nije postavljen. Na takvu adresu moguće je unapred poslati sredstva.

active znači da su kod i početni podaci postavljeni i da contract može da obrađuje poruke.

frozen nastaje kada nalog ne može da izmiri naknade za čuvanje persistentnog stanja. Za ponovno aktiviranje potrebni su odgovarajući podaci i plaćanje duga, dok dovoljno veliki neizmireni dug može dovesti do uklanjanja naloga.

Ovaj model omogućava zanimljiv deployment workflow. Adresa contracta može se izračunati pre nego što je contract deployovan, jer se izvodi iz njegovog početnog stanja.

StateInit i determinističke adrese

StateInit opisuje početno stanje smart contracta. U praksi obuhvata njegov kod i početne podatke, uz dodatna protocol-level polja koja format podržava.

Adresa contracta izvodi se iz hash vrednosti njegovog početnog stanja i workchain identifikatora. To znači da developer može:

izračunati adresu pre deploymenta
prikazati je korisniku
poslati sredstva na nju
kasnije poslati deployment poruku sa odgovarajućim StateInit
proveriti da li se očekivani kod nalazi na očekivanoj adresi

Promena samo jednog bita početnog koda ili podataka proizvodi drugačiju adresu.

Ovo je korisno kod factory contracta, jetton walleta, NFT itema i drugih obrazaca gde se veliki broj naloga kreira deterministički.

Istovremeno, prefunding adrese nosi rizik. Ako aplikacija pogrešno izračuna StateInit, sredstva mogu završiti na adresi koja nikada neće biti aktivirana očekivanim kodom.

Zato logiku za računanje adrese ne treba kopirati na više mesta. Treba je staviti u isti wrapper koji se koristi za deployment, testiranje i slanje poruka.

Wallet na TON-u je smart contract

Wallet adresa nije isto što i javni ključ.

Wallet je smart contract koji proverava vlasništvo nad ključem, sprovodi replay zaštitu i šalje interne poruke drugim nalozima. Standardni wallet contract obično čuva:

javni ključ vlasnika
seqno
wallet_id ili subwallet_id
podatke specifične za verziju walleta

Privatni ključ ostaje van blockchaina.

Korisnik ili wallet aplikacija formiraju zahtev, potpisuju ga i šalju kao eksternu poruku wallet contractu. Contract proverava potpis i pravila zahteva, a zatim generiše interne poruke.

Wallet ne čuva sopstveni balans kao običnu promenljivu. Balans je deo protocol-level stanja naloga i validatori ga ažuriraju kada sredstva stignu, budu poslata ili potrošena na naknade.

seqno je brojač koji sprečava ponovno izvršavanje iste potpisane poruke. Wallet prihvata očekivanu vrednost i nakon uspešne obrade povećava brojač.

valid_until ograničava trajanje zahteva. Potpisana poruka koja nije uključena u mrežu pre isteka ne bi trebalo da ostane zauvek validna.

wallet_id razdvaja različite wallet instance koje mogu koristiti isti javni ključ. Zbog toga isti mnemonic ili public key ne moraju proizvesti istu adresu za svaku verziju wallet contracta, mrežu ili subwallet konfiguraciju.

Backend koji generiše wallet adrese mora zato eksplicitno znati:

verziju wallet contracta
mrežu
wallet_id
workchain
javni ključ

Pretpostavka da je adresa samo hash javnog ključa dovodi do pogrešnih adresa i potencijalnog gubitka sredstava.

Eksterne i interne poruke

TON koristi tri osnovne kategorije poruka:

incoming external messages
internal messages
outgoing external messages

Incoming external message dolazi izvan blockchaina. Tipičan primer je zahtev koji wallet aplikacija šalje wallet contractu.

Takva poruka ne može da donese Gram iz spoljnog sveta. Contract koji je prihvati može trošak izvršavanja platiti iz sopstvenog balansa.

Internal message šalje jedan blockchain nalog drugom. Ona može sadržati:

adresu primaoca
prenetu vrednost
telo poruke
opcioni StateInit
bounce podešavanje
parametre relevantne za prosleđivanje

Outgoing external message izlazi iz blockchain okruženja i može služiti kao događaj namenjen spoljnim servisima i indexerima.

Za većinu dApp tokova najvažnije su eksterne poruke ka walletima i interne poruke između contracta.

Eksterna poruka obično pokreće wallet, a wallet zatim šalje internu poruku dApp contractu.

Poruka nije transakcija

Ova razlika je važna za praćenje uplata.

Poruka predstavlja zahtev ili nameru. Transakcija je rezultat obrade poruke na određenom nalogu.

Ako korisnik potpiše zahtev u walletu, to još uvek ne znači da je poslovna operacija završena. Čak ni pojavljivanje prve wallet transakcije ne znači da je svaki contract u traceu uspešno izvršio svoj deo posla.

Na primer, wallet transakcija može uspešno poslati tri interne poruke. Jedna od njih može biti obrađena, druga odbijena, a treća vraćena kroz bounce.

TON Connect može vratiti BoC potpisane eksterne poruke, ali taj odgovor nije dokaz da je primalac uspešno obradio transfer. Rezultat treba pronaći i proveriti on-chain.

Pouzdan statusni model na backendu može izgledati ovako:

created
awaiting_signature
submitted
observed
processing
confirmed
failed
expired

submitted znači da je zahtev potpisan ili prosleđen.

observed znači da je odgovarajuća transakcija pronađena na mreži.

confirmed treba koristiti tek kada su provereni relevantni primaoci, iznosi, payload, statusi transakcija i očekivani ishod tracea.

Faze TON transakcije

Obična TON transakcija ne sastoji se samo od pokretanja contract koda. Obrada prolazi kroz više faza.

Relevantne faze su:

storage
credit
compute
action
bounce

Tačan redosled zavisi od karakteristika poruke, uključujući bounce podešavanje.

U storage fazi obračunavaju se troškovi čuvanja stanja naloga.

U credit fazi vrednost dolazne interne poruke pripisuje se nalogu.

U compute fazi TVM izvršava contract kod.

U action fazi mreža obrađuje akcije koje je contract pripremio tokom izvršavanja. To mogu biti slanje poruke, rezervisanje sredstava, promena koda ili rad sa bibliotekama.

U bounce fazi može se formirati povratna poruka kada obrada ne uspe pod uslovima koji dozvoljavaju bounce.

Compute faza i action faza nisu ista stvar.

Contract može uspešno završiti računanje i pripremiti izlazne poruke, ali neka izlazna akcija ipak može biti neuspešna. Zato test koji proverava samo TVM exit code ne mora dokazivati da je poslovni tok uspeo.

Za svaku važnu operaciju treba proveriti:

da li je transakcija aborted
compute exit code
action result code
broj kreiranih poruka
primaoce poruka
prenete iznose
bounce poruke
završno stanje contracta
nastavak tracea

Šta su send modes

Kada contract šalje internu poruku, send mode određuje kako se vrednost i greške tretiraju.

Različiti modovi i zastavice mogu uticati na to:

da li se naknade plaćaju odvojeno
da li poruka prenosi preostalu vrednost primljene poruke
da li se šalje preostali balans contracta
da li se pojedine greške ignorišu
da li neuspeh akcije treba da izazove bounce
da li se nalog uklanja ako balans postane nula

Send mode nije detalj koji treba nasumično kopirati iz primera.

Posebno su opasni modovi koji ignorišu greške. Oni mogu biti opravdani u određenom protokolarnom toku, ali mogu i proizvesti situaciju u kojoj početna transakcija izgleda uspešno, dok očekivana izlazna poruka nije poslata.

Svaki send mode treba posmatrati kao deo poslovne semantike contracta, a ne samo optimizaciju naknade.

Bounce nije globalni rollback

Bounce poruka obaveštava pošiljaoca da primalac nije obradio poruku kako je očekivano. Ona može vratiti deo preostale vrednosti i podatke koji omogućavaju povezivanje sa prvobitnim zahtevom.

To nije globalni rollback kompletnog tracea.

Ako je contract A promenio svoje stanje i poslao poruku contractu B, neuspeh contracta B ne mora automatski vratiti contract A u prethodno stanje.

Contract A zato treba eksplicitno da podrži kompenzacioni tok.

Primer:

Contract A primi zahtev za isplatu.
Contract A označi zahtev kao pending.
Contract A pošalje sredstva contractu B.
Ako obrada uspe, A kasnije dobija potvrdu ili se ishod verifikuje kroz očekivani tok.
Ako poruka bude vraćena, A obrađuje bounce i vraća zahtev u available ili failed stanje.

Loš obrazac je smanjiti korisnički balans, poslati poruku i ne implementirati bounce handler. U slučaju neuspeha sredstva se možda vrate contractu, ali interna evidencija korisnika ostaje pogrešna.

Za povezivanje zahteva i odgovora često se koristi query_id. On treba da bude dovoljno jedinstven u domenu contracta i vezan za zapis operacije koja je u toku.

Cells su osnovni format podataka

TON ne čuva persistentno stanje kao proizvoljan niz bajtova niti koristi klasičan ABI model identičan EVM-u.

Osnovna jedinica podataka je cell.

Jedna cell može sadržati:

najviše 1023 bita podataka
najviše četiri reference na druge cells

Reference formiraju usmereni aciklični graf. Ciklične reference nisu dozvoljene.

Cells se koriste za:

smart contract kod
persistentne podatke
tela poruka
StateInit
transakcije
blokove
Merkle dokaze
dictionaries

Ograničenje od 1023 bita ne znači da poruka ili contract mogu imati samo toliko podataka. Veće strukture se dele kroz reference ka drugim cells.

Ipak, raspored podataka utiče na cenu. Više cells i referenci može povećati storage i forwarding naknade.

Developer zato mora razmišljati o binarnom layoutu, ne samo o logičkoj strukturi objekta.

Builder, Cell i Slice

Pri radu sa cells često se koriste tri mentalna modela.

Builder služi za kreiranje cell strukture. U njega se upisuju bitovi, brojevi, adrese, token iznosi i reference.

Cell predstavlja završenu strukturu.

Slice predstavlja cursor za čitanje sadržaja cella.

Jednostavan komentar ili identifikator fakture može se napraviti pomoću @ton/core paketa:

import { beginCell, Cell } from "@ton/core";

function createInvoicePayload(invoiceId: string): Cell {
    return beginCell()
        .storeUint(0, 32)
        .storeStringTail(`invoice:${invoiceId}`)
        .endCell();
}

Nulti 32-bitni prefiks koristi se kao konvencija za tekstualni komentar. Primalac zatim ostatak sadržaja može čitati kao UTF-8 string.

Za contract protokol je obično bolji strukturirani binarni payload:

import { beginCell, Cell } from "@ton/core";

function createPaymentPayload(
    queryId: bigint,
    invoiceNumber: bigint,
): Cell {
    return beginCell()
        .storeUint(0x70617901, 32)
        .storeUint(queryId, 64)
        .storeUint(invoiceNumber, 64)
        .endCell();
}

Ovde je 0x70617901 aplikacioni opcode. Vrednost opkoda treba dokumentovati i držati stabilnom nakon objave protokola.

Contract mora čitati polja istim redosledom i istom širinom:

opcode kao 32-bitni unsigned integer
queryId kao 64-bitni unsigned integer
invoiceNumber kao 64-bitni unsigned integer

Ako serializer piše uint64, a parser očekuje uint32, protokol je pokvaren čak i kada se obe strane kompajliraju bez greške.

Bag of Cells i BoC

Stablo cells se pri prenosu ili čuvanju serijalizuje kao Bag of Cells, odnosno BoC.

BoC se često pojavljuje kao:

base64 string u API odgovoru
binarni deployment artifact
rezultat koji vraća TON Connect
serijalizovano telo poruke
ulaz za emulaciju transakcije
dokaz stanja ili transakcije

BoC može sadržati više root cells. Interno može eliminisati duplikate, jer se cells sa istim hashom mogu deliti između više grana grafa.

Kada TON Connect vrati result.boc, ne vraća JSON opis uspešnog transfera. Vraća serijalizovanu eksternu poruku koju treba povezati sa stvarnim on-chain transakcijama.

Backend ili indexer zato mora znati kako da:

izračuna hash poruke
pronađe transakciju koja ju je obradila
prati izlazne interne poruke
dekodira njihova tela
proveri kompletan ishod

TL-B je deo javnog interfejsa

TL-B je jezik šema koji TON koristi za opis binarnih struktura.

Njime su opisani:

blokovi
transakcije
poruke
adrese
StateInit
currency collections
standardni token interfejsi

U Solidity svetu ABI često daje gotov opis funkcija i tipova. Na TON-u je TL-B šema bliža preciznom wire protocolu.

Jetton transfer, na primer, nije poziv metode u klasičnom smislu. To je cell čiji sadržaj prati standardizovani TL-B raspored.

Zato dokumentacija smart contracta treba da sadrži najmanje:

opcode svake poruke
raspored polja
bit width brojeva
da li se podatak čuva inline ili u referenci
semantiku query_id
očekivanu vrednost poruke
bounce ponašanje
moguće exit kodove
očekivane izlazne poruke

Binarna šema je API contracta. Njena promena bez plana kompatibilnosti jednaka je breaking promeni HTTP API-ja.

TON Virtual Machine

TON Virtual Machine je stack-based virtuelna mašina koja izvršava smart contract kod i ima ugrađene operacije za rad sa cells, slices, builders, dictionaries i kriptografskim funkcijama.

Persistentno stanje contracta ulazi u izvršavanje kao cell. Nakon uspešnog izvršavanja nova vrednost persistentnog stanja može biti sačuvana.

Contract tokom compute faze formira listu akcija. U action fazi mreža izvršava te akcije.

Među protocol-level akcijama nalaze se:

slanje poruke
rezervisanje sredstava
promena koda
rad sa bibliotekama

Jedna transakcija može pripremiti najviše 255 akcija.

Get metode se izvršavaju drugačije. One se pokreću lokalno preko nodea ili providera, ne menjaju blockchain stanje i korisnik ne šalje on-chain transakciju samo da bi pročitao rezultat.

To ih čini pogodnim za:

čitanje konfiguracije contracta
prikaz stanja u frontendu
dobijanje token podataka
računanje determinističke adrese
proveru vlasništva
dobijanje seqno vrednosti walleta

Drugi smart contract ne može jednostavno sinhrono pozvati get metodu drugog contracta. On-chain komunikacija i dalje se odvija porukama.

Jezici i razvojni alati

Zvanični jezik za nove TON smart contracte je Tolk. FunC ostaje važan zbog velikog broja postojećih contracta i biblioteka, ali se tretira kao legacy put za održavanje starijeg koda.

U ekosistemu se koristi i Tact, posebno za projekte kojima odgovara viši nivo apstrakcije. Izbor jezika treba zasnovati na:

zrelosti toolchaina
dostupnosti biblioteka
iskustvu tima
potrebi za kontrolom nad serijalizacijom
zahtevima audita
kompatibilnosti sa postojećim contractima

Za TypeScript orijentisan razvoj često se koristi Blueprint. Osnovni workflow uključuje generisanje projekta, build, lokalno testiranje, deployment skripte i wrappere.

npm create ton@latest
cd example-project
npm install

npx blueprint build
npx blueprint test

Tačan interaktivni izbor templatea i jezika zavisi od verzije alata. Komande, nazive templatea i konfiguraciju ne treba prepisivati iz starog blog posta bez poređenja sa dokumentacijom instalirane verzije.

Wrapper je posebno važan deo TON projekta. On na jednom mestu treba da sadrži:

izračunavanje adrese
kreiranje StateInit
serijalizaciju poruka
parsiranje get metoda
deployment logiku
TypeScript tipove
helper metode za testove i skripte

Dobar wrapper sprečava da frontend, backend i deployment skripta svako na svoj način formiraju isti cell.

Kako treba testirati TON contract

Unit test koji pozove handler i proveri jednu promenljivu nije dovoljan.

TON contract treba testirati kroz poruke i njihove posledice. Sandbox test treba da proveri kompletan skup transakcija koje su nastale tokom tracea.

Koristan test proverava:

pošiljaoca ulazne poruke
primaoca
bounce flag
vrednost poruke
opcode
exit code
action status
izlazne poruke
njihove vrednosti i payload
završno persistentno stanje
promenu balansa
vraćene excess poruke
bounce obradu

Obavezni negativni testovi uključuju:

poruku od neovlašćenog pošiljaoca
duplirani query_id
nepoznat opcode
premalo priložene vrednosti
malformed cell
pogrešnu adresu
pogrešan workchain
bounce očekivane izlazne poruke
paralelne operacije nad istim stanjem
pokušaj ponavljanja eksterne poruke
ekstremne granične vrednosti

Za debugging treba posmatrati ceo trace. Ako prva transakcija prođe, a poslednja ne promeni očekivano stanje, problem se često nalazi u poruci između njih, nedovoljnoj vrednosti ili action fazi.

TON Connect povezuje aplikaciju i wallet

TON Connect je standardni protokol za povezivanje dApp-a sa TON walletima.

On aplikaciji omogućava da:

dobije adresu izabranog walleta
zatraži dokaz kontrole nad adresom
zatraži potpis
pošalje zahtev za transakciju
obnovi postojeću sesiju

Aplikacija pritom ne dobija privatni ključ korisnika.

TON Connect koristi dApp, wallet i bridge. Bridge prenosi end-to-end šifrovane poruke i ne treba da ima pristup njihovom otvorenom sadržaju.

Za React aplikacije koristi se @tonconnect/ui-react:

npm install @tonconnect/ui-react

Aplikacija mora imati javno dostupan manifest:

{
  "url": "https://example.com",
  "name": "Example App",
  "iconUrl": "https://example.com/icon-180.png"
}

Manifest treba da bude dostupan preko HTTPS-a, bez autentifikacije, CORS blokade ili proxy challenge stranice. Wallet ga koristi da korisniku prikaže identitet aplikacije.

Provider se zatim postavlja oko React aplikacije:

"use client";

import {
    TonConnectButton,
    TonConnectUIProvider,
} from "@tonconnect/ui-react";

export function Providers({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <TonConnectUIProvider
            manifestUrl={
                "https://example.com/tonconnect-manifest.json"
            }
        >
            <TonConnectButton />
            {children}
        </TonConnectUIProvider>
    );
}

Kod Next.js App Router aplikacije provider mora biti u client komponenti, jer SDK koristi browser funkcionalnosti poput lokalnog storagea i modala.

Slanje transakcije preko TON Connecta

TON Connect sendTransaction prima zahtev sa rokom važenja i jednom ili više poruka.

"use client";

import { beginCell, toNano } from "@ton/core";
import {
    useTonConnectUI,
    useTonWallet,
} from "@tonconnect/ui-react";

export function PaymentButton({
    recipient,
    invoiceId,
}: {
    recipient: string;
    invoiceId: string;
}) {
    const wallet = useTonWallet();
    const [tonConnectUi] = useTonConnectUI();

    async function pay() {
        const payload = beginCell()
            .storeUint(0, 32)
            .storeStringTail(`invoice:${invoiceId}`)
            .endCell();

        const result = await tonConnectUi.sendTransaction({
            validUntil: Math.floor(Date.now() / 1000) + 300,
            network: "-239",
            messages: [
                {
                    address: recipient,
                    amount: toNano("0.05").toString(),
                    payload: payload.toBoc().toString("base64"),
                },
            ],
        });

        console.log(result.boc);
    }

    return (
        <button disabled={!wallet} onClick={pay}>
            Potvrdi plaćanje
        </button>
    );
}

network vrednost -239 označava mainnet, dok se za testnet koristi -3.[14]

Iznos se šalje kao decimalni string najmanjih jedinica. Payload je base64 kodiran BoC.

Ovaj kod inicira wallet tok, ali ne treba da aktivira proizvod odmah nakon što sendTransaction vrati rezultat. Vraćeni BoC treba sačuvati kao podatak za praćenje, a uplatu potvrditi nakon provere blockchaina.

Takođe, više poruka u jednom wallet zahtevu nisu jedna atomska operacija na svim primaocima. Wallet može potpisati i poslati paket, ali svaki primalac obrađuje svoju poruku nezavisno. Jedna može uspeti, a druga pasti.

ton_proof za autentifikaciju

Povezana wallet adresa sama po sebi nije dovoljna za backend login.

Frontend može backendu poslati bilo koju adresu kao string. Backend mora dobiti kriptografski dokaz da korisnik kontroliše odgovarajući wallet.

TON Connect za to koristi ton_proof.

Tipičan tok izgleda ovako:

Backend generiše jednokratni nonce.
Nonce se vezuje za sesiju, domen i rok važenja.
Frontend zahteva ton_proof prilikom povezivanja walleta.
Wallet potpisuje strukturiranu poruku.
Frontend šalje proof backendu.
Backend proverava payload, domen, timestamp, adresu, StateInit, javni ključ i Ed25519 potpis.
Nonce se označava kao iskorišćen.
Backend izdaje sopstvenu aplikacionu sesiju.

Potpis je vezan za wallet adresu, domen aplikacije, vreme i payload. Time se smanjuje rizik da proof napravljen za jednu aplikaciju bude iskorišćen na drugom domenu.

Javni ključ iz odgovora ne treba slepo prihvatiti. Backend treba da proveri njegovu vezu sa wallet adresom i StateInit, ili da koristi odgovarajući on-chain metod kada je potrebno.

Nonce mora biti:

kriptografski nasumičan
kratkog roka
vezan za konkretnu sesiju
neupotrebljiv nakon prve uspešne provere

ton_proof potvrđuje kontrolu nad walletom. Ne potvrđuje da korisnik poseduje određeni token, da je izvršio uplatu ili da je konkretna transakcija uspešna. To su odvojene provere.

Realan payment workflow

Zamislimo Telegram Mini App koji prodaje digitalnu uslugu.

Korisnik bira paket i plaća izvorном valutom mreže. Pouzdan sistem treba da razdvoji kreiranje narudžbine, potpisivanje i blockchain potvrdu.

Backend prvo kreira invoice:

{
  "invoiceId": "inv_8d712",
  "userId": "usr_184",
  "asset": "GRAM",
  "amountNano": "50000000",
  "recipient": "UQ...",
  "status": "created",
  "expiresAt": 1760000000
}

Vreme u primeru je samo Unix vrednost u podacima, ne hardkodovana poslovna konstanta.

Backend zatim vraća frontendu:

adresu primaoca
tačan iznos u najmanjim jedinicama
payload sa invoice identifikatorom
dozvoljenu mrežu
rok važenja zahteva

Frontend ne bi trebalo sam da odlučuje koliko treba platiti i kome. U suprotnom korisnik ili izmenjeni klijent mogu promeniti parametre pre otvaranja walleta.

Nakon potpisa backend prati mrežu i proverava:

da li je primalac tačan
da li je asset tačan
da li je iznos dovoljan
da li payload sadrži očekivani invoice ID
da li invoice postoji
da li je invoice još validan
da li uplata već nije obrađena
da li je relevantna transakcija uspešna
da li postoji neočekivani bounce
da li je trace dostigao očekivano završno stanje

Tek tada se invoice označava kao plaćen.

Idempotency nije opcioni detalj

Blockchain event može biti obrađen više puta.

Razlozi uključuju:

restart workera
ponovni API zahtev
preklapanje pollinga i streama
retry nakon timeouta
ponovno indeksiranje
ručni reconciliation
duplirani webhook

Backend zato mora imati stabilan identitet uplate.

To može biti kombinacija:

account_address
transaction_lt
transaction_hash
message_hash

Ili jedinstveni aplikacioni identifikator povezan sa verifikovanom transakcijom.

Baza treba da ima unique constraint koji sprečava dvostruko kreditiranje.

CREATE UNIQUE INDEX payments_chain_identity_unique
ON payments (
    network,
    account_address,
    transaction_lt,
    transaction_hash
);

Business handler zatim treba da bude idempotentan:

begin transaction

insert payment if not exists

if payment already processed:
    return previous result

mark invoice as paid
grant purchased entitlement
mark payment as processed

commit

Bez ovoga, savršeno validna blockchain integracija može napraviti duplu internu uplatu zbog običnog backend retryja.

Kako čitati TON blockchain

DApp obično ne komunicira direktno sa validatorima iz browsera. Koriste se API provideri, liteserveri i indeksirani data servisi.

TON Center API v3 predstavlja indeksirani sloj koji omogućava pretragu:

transakcija
poruka
traceova
akcija
jetton transfera
NFT podataka
istorijskih događaja

Postoje endpointi za pronalaženje transakcija na osnovu message hasha i za čitanje dekodiranih akcija.

Indexirani API je praktičan, ali uvodi poverenje u provider. Provider može kasniti, pogrešno dekodirati podatke ili biti nedostupan.

Za kritičnije sisteme mogu se koristiti:

sopstveni full node
liteserver
archive infrastruktura
sopstveni indexer
provera Merkle dokaza
kombinacija više nezavisnih providera

Full node i archive node nisu ista stvar. Full node može čuvati aktuelno stanje i novije blokove uz pruning, dok je archive infrastruktura potrebna kada servis mora pouzdano da pretražuje kompletnu istoriju.

Razuman produkcioni kompromis često izgleda ovako:

Primarni indexed API za brzo čitanje.
Drugi provider za proveru kritičnih podataka.
Lokalna baza sa sopstvenim cursorom.
Periodični reconciliation starijih transakcija.
Alert kada indexer lag pređe dozvoljeni prag.
Mogućnost ponovne obrade određenog raspona blokova.

Jettoni nisu centralizovani ERC-20 mapping

Fungibilni tokeni na TON-u nazivaju se jettons. Standardni interfejs opisan je kroz TEP-74.

Kod tipičnog ERC-20 contracta jedan contract čuva mapping svih adresa i balansa.

Kod jettona se koriste:

jetton master contract
pojedinačni jetton wallet contracti

Master contract čuva opšte podatke o tokenu, kao što su ukupna ponuda, metadata i kod wallet contracta.

Svaki vlasnik ima sopstveni jetton wallet contract za konkretan jetton.

Ako token ima tri vlasnika, u jednostavnom modelu postoje jedan master i tri jetton wallet contracta.

Jetton transfer zato nije samo promena dva polja u jednom centralnom mappingu. Tipičan tok uključuje:

Korisnikov običan wallet šalje poruku njegovom jetton walletu.
Pošiljaočev jetton wallet smanjuje balans.
On šalje internu transfer poruku jetton walletu primaoca.
Primaočev jetton wallet povećava balans.
Po potrebi se šalje transfer_notification krajnjem primaocu.
Višak izvorne valute vraća se kroz excesses poruku.

Ako primaočev jetton wallet još ne postoji, može biti deterministički deployovan tokom transfera.

Ovaj model raspoređuje stanje i izvršavanje između više contracta, što se uklapa u sharding arhitekturu TON-a. Cena je složenija integracija.

Bezbedna obrada jetton uplata

Naziv, simbol i slika jettona nisu dokaz identiteta.

Napadač može napraviti token sa istim nazivom i logotipom kao poznati stablecoin. Aplikacija koja proverava samo metadata podatke može prihvatiti bezvredni lažni token.

Pouzdana integracija održava allowlist jetton master adresa.

Kada servis primi transfer_notification, treba proveriti:

opcode 0x7362d09c
adresu contracta koji je poslao poruku
vezu između tog jetton walleta i odobrenog mastera
vlasnika očekivanog jetton walleta
iznos u osnovnim jedinicama
query_id
originalnog pošiljaoca
forward_payload
bounce indikatore
neočekivane izlazne poruke

Odnos mastera i walleta proverava se korišćenjem standardnog get_wallet_address() metoda na pouzdanom jetton master contractu. Dobijena adresa mora odgovarati jetton walletu koji je poslao notifikaciju.

TEP-74 definiše standardne poruke, uključujući:

transfer
internal_transfer
transfer_notification
excesses
burn
burn_notification

transfer_notification se šalje samo ako je forward_ton_amount veći od nule. Servisi koji zavise od notifikacije moraju to uzeti u obzir pri formiranju transfera.

Jetton iznosi takođe nisu nužno u devet decimala. Broj decimala zavisi od konkretnog tokena. Backend mora čuvati integer količinu i zasebno metadata informaciju potrebnu za prikaz.

Koliko košta TON transakcija

TON nema jednu fiksnu naknadu za svaku transakciju.

Ukupan trošak može uključiti:

storage fee
compute fee
import fee
action fee
forward fee

Storage fee zavisi od količine persistentnih podataka i vremena tokom kojeg se čuvaju.

Compute fee zavisi od potrošenog TVM gasa.

Import fee odnosi se na obradu ulazne eksterne poruke.

Action i forward fee zavise od izlaznih akcija, veličine poruka, broja cells i njihovog prosleđivanja.

Zbog toga jednostavan transfer, deployment contracta i jetton transfer nemaju isti trošak.

Jetton transfer može uključiti više contracta i poruka:

wallet
sender jetton wallet
receiver jetton wallet
recipient
response destination

Svaki dodatni korak može imati sopstveni compute i forwarding trošak.

Naknada zavisi i od konfiguracionih parametara mreže. Vrednosti se mogu menjati, pa ih ne treba trajno hardkodovati u poslovnu logiku.

Praktičan pristup je:

Izgraditi tačnu poruku.
Emulirati ili proceniti transakciju preko pouzdanog providera.
Dodati razumnu rezervu.
Nakon izvršenja pročitati stvarno potrošene naknade.
Pratiti odstupanje procene od realnog troška.

Za aplikaciju je često važniji maksimalni dozvoljeni trošak operacije nego prosečna naknada.

Ako ugovor mora da pošalje četiri izlazne poruke, treba dokazati da priložena vrednost pokriva najgori podržani slučaj, ne samo srećnu putanju iz jednog testa.

Storage nije besplatan posle deploymenta

Smart contract nije datoteka koja se jednom uploaduje i zatim zauvek ostaje bez troška.

Persistentni kod i podaci imaju storage cenu. Ako contract čuva sve veći dictionary korisnika, narudžbina ili istorijskih događaja, trošak može rasti tokom vremena.

Zato nije dobro automatski čuvati svaki događaj on-chain.

Primeri podataka koji često ne moraju biti u persistentnom contract stanju:

kompletna istorija promena
analitički podaci
pretraživi tekst
korisnički profili
logovi
podaci koji se mogu rekonstruisati iz transakcija
privatne informacije
veliki metadata dokumenti

On-chain treba čuvati minimalno stanje potrebno za verifikaciju i sprovođenje pravila.

Umesto kompletne liste dokumenata, contract može čuvati Merkle root. Umesto istorije svih statusa, može čuvati samo trenutno stanje i emitovati događaje za indexer.

Konsenzus, finalnost i šta aplikacija zapravo čeka

TON koristi Proof-of-Stake. Validatori učestvuju u predlaganju i potvrđivanju blokova, dok masterchain daje zajednički pogled na stanje shardchainova.

Dokumentacija opisuje finalnost koja se u uobičajenim uslovima postiže ispod jedne sekunde. To treba posmatrati kao karakteristiku protokola, ne kao garantovani application-level SLA.

Korisnik može ipak čekati duže zbog:

wallet UI-ja
slanja preko bridgea
API pollinga
indexer laga
obrade tracea sa više poruka
backend queuea
baze podataka
retry politike

Ako frontend proverava status jednom u deset sekundi, mrežna finalnost ispod sekunde neće proizvesti brz korisnički doživljaj.

Produkcioni sistem treba da meri najmanje:

wallet_signed_at
submitted_at
first_seen_at
included_at
business_confirmed_at

Tako se može utvrditi da li usporenje dolazi iz walleta, providera, indexera ili sopstvenog backenda.

Bezbednost eksternih poruka

Incoming external message ne donosi sredstva contractu. Contract ima ograničen gas credit da proveri zahtev pre nego što prihvati plaćanje daljeg izvršavanja iz sopstvenog balansa.

Ako contract prerano izvrši ACCEPT, napadač može ponavljati nevalidne zahteve i trošiti njegov balans.

Pre prihvatanja eksterne poruke obično treba proveriti:

potpis
seqno
valid_until
wallet_id
očekivani format
domen ili kontekst potpisa
dozvoljenu operaciju

Nakon uspešne provere contract može prihvatiti poruku i promeniti stanje.

Nedostatak replay zaštite je posebno opasan. Validno potpisan zahtev ne sme moći da se izvrši više puta.

Za većinu dApp contracta jednostavniji i sigurniji model je da primaju interne poruke iz standardnog walleta, umesto da samostalno implementiraju složenu obradu eksternih potpisa.

Adrese, bounceable format i validacija

TON adresa može biti prikazana u raw ili user-friendly formatu.

Raw oblik izgleda kao workchain i 256-bitni identifikator:

0:b4c1b2ede12aa76f4a44353944258bcc8f99e9c7c474711a152c78b43218e296

User-friendly format uključuje dodatne zastavice i checksum. Može označiti da li je adresa bounceable i da li pripada test mreži.

Različiti tekstualni oblici mogu predstavljati isti underlying nalog.

Backend zato ne treba da poredi adrese običnim poređenjem originalnih stringova. Potrebno ih je parsirati i normalizovati pomoću proverene biblioteke.

import { Address } from "@ton/core";

const first = Address.parse(inputAddress);
const second = Address.parse(storedAddress);

const sameAccount = first.equals(second);

Treba proveriti i workchain. Aplikacija koja očekuje basechain nalog ne bi trebalo da prihvati proizvoljnu adresu bez provere.

Bounceable adresa je prikladna kada se očekuje aktivan contract i kada pošiljalac želi povratnu poruku u slučaju neuspeha.

Non-bounceable format je često prikladniji za prvi transfer ka još nedeployovanoj wallet adresi. To nije univerzalno pravilo za svaki protokol, već deo odluke o očekivanom stanju primaoca.

Zašto kompletan backend i dalje ostaje potreban

TON ne uklanja potrebu za klasičnim backendom.

Blockchain dobro rešava:

javno proverljivo vlasništvo
prenos vrednosti
zajedničko stanje između nepouzdanih strana
pravila koja ne zavise od jednog servera
transparentnu evidenciju izvršenja

Klasičan backend je obično bolji za:

pretragu
analitiku
privatne podatke
email i push obaveštenja
rate limiting
preporuke
moderaciju
korisničku podršku
kompleksne izveštaje
brzo keširanje
poslovne integracije

Najzdravija arhitektura nije „sve on-chain“, već jasna podela odgovornosti.

Smart contract treba da bude mali, determinističan i proverljiv. Backend treba da indeksira događaje, održava aplikacione projekcije, prati neuspešne tokove i pruža korisniku razumljiv interfejs.

Predložena arhitektura produkcione aplikacije

Za ozbiljniji TON proizvod razumno je odvojiti nekoliko komponenti.

Frontend ili Mini App prikazuje korisnički interfejs i koristi TON Connect za wallet sesiju.

Application backend upravlja korisnicima, invoiceima, dozvolama i poslovnom logikom koja ne mora biti on-chain.

Transaction builder formira očekivane poruke i payload. Za finansijske operacije često je sigurnije da backend napravi parametre nego da ih frontend slobodno sastavlja.

Blockchain listener prati naloge, transakcije, poruke i traceove.

Decoder parsira standardne i aplikacione TL-B poruke.

Reconciliation worker ponovo proverava nepotvrđene i ranije obrađene transakcije.

Database čuva raw blockchain identitete, dekodirane događaje i aplikacione projekcije.

Smart contract wrapper obezbeđuje isti binarni format u testovima, skriptama i aplikacionom kodu.

Tok može izgledati ovako:

flowchart LR
    U[Korisnik] --> F[Frontend ili Mini App]
    F --> TC[TON Connect]
    TC --> W[Wallet]
    W --> N[TON mreža]
    F --> B[Application backend]
    B --> D[(Baza)]
    N --> I[Indexer ili liteserver]
    I --> L[Blockchain listener]
    L --> V[Validator poslovnih pravila]
    V --> D
    D --> R[Reconciliation worker]
    R --> I

Ključna tačka je da wallet odgovor i blockchain potvrda ulaze u sistem različitim putem. Frontend inicira nameru, dok listener potvrđuje izvršenje.

Gde TON ima praktičnog smisla

TON je posebno zanimljiv kada aplikacija ima prirodnu vezu sa Telegram okruženjem ili zahteva veliki broj relativno nezavisnih on-chain interakcija.

Primeri uključuju:

plaćanja u Telegram Mini Apps aplikacijama
digitalnu robu
pretplate
nagrade i loyalty programe
igre sa digitalnim vlasništvom
marketplace tokove
escrow contracte
NFT kolekcije
community tokene
mikroplaćanja
DeFi protokole
servise sa mnogo pojedinačnih korisničkih stanja

To ne znači da svaki Telegram bot treba blockchain.

Ako proizvod ima jednog operatera, nema potrebu za javno proverljivim vlasništvom i sve transakcije se mogu pouzdano voditi u običnoj bazi, blockchain može dodati više složenosti nego vrednosti.

TON ima smisla kada su javno vlasništvo, prenosiva sredstva, interoperabilnost i izvršavanje bez centralnog posrednika stvarni deo proizvoda.

Glavni trade-offi

TON-ov sharding i message-driven model omogućavaju horizontalno skaliranje, ali prenose deo složenosti na aplikacionu arhitekturu.

Asinhronost otežava višekoračne operacije. Potrebni su statusi, query_id, bounce handleri i kompenzacione akcije.

Binarna serijalizacija traži disciplinu. Cell koji je pogrešno pročitan za jedan bit može potpuno promeniti značenje poruke.

Jetton model povećava broj contracta. Distribuirano stanje olakšava skaliranje, ali transfer više nije promena jednog centralnog mappinga.

Indexer postaje važan deo proizvoda. Korisnik ne želi da ručno pregleda block explorer kako bi saznao zašto uplata nije prepoznata.

Provider ubrzava razvoj, ali uvodi poverenje. Sopstveni node smanjuje zavisnost, ali povećava operativni trošak.

Brza finalnost ne rešava spor backend. Observability i event processing ostaju odgovornost aplikacije.

Niske naknade nisu isto što i neograničeno besplatno stanje. Storage, broj poruka i veličina payload-a i dalje imaju cenu.

Telegram distribucija može postati platformska zavisnost. Blockchain domen i poslovnu logiku treba odvojiti od konkretnog Mini App interfejsa.

Kako bih procenjivao TON za novi projekat

Pre izbora mreže postavio bih nekoliko praktičnih pitanja.

Da li proizvod dobija konkretnu vrednost iz TON wallet i Telegram ekosistema?

Da li se poslovni proces može modelovati kao asinhrona state machine?

Da li tim razume da jedan korisnički zahtev može proizvesti više blockchain transakcija?

Da li postoji plan za bounce, retry, timeout i reconciliation?

Da li se svi finansijski iznosi čuvaju u najmanjim jedinicama?

Da li smart contract može ostati dovoljno mali da bude temeljno testiran i auditovan?

Da li postoji jasan razlog zbog kojeg određeni podatak mora biti on-chain?

Da li tim može da održava indexer ili pouzdano upravlja eksternim providerom?

Da li je korisničko iskustvo prihvatljivo kada wallet ili provider privremeno nisu dostupni?

Ako su odgovori pozitivni, TON može biti dobar izbor za aplikacije koje zahtevaju veliki broj brzih transfera, distribuirano vlasništvo i prirodnu integraciju sa walletima.

Ako aplikacija zahteva velike sinhrone operacije preko mnogo contracta, intenzivno privatno računanje ili čuvanje velike količine podataka, klasičan backend ili drugačiji blockchain model mogu biti jednostavniji.

Najvažnije je ne birati TON samo na osnovu jedne brojke o brzini ili prosečnoj naknadi.

Njegova prava tehnička vrednost nalazi se u arhitekturi: nalozi kao nezavisni akteri, komunikacija porukama, determinističke adrese, cell-based podaci i mogućnost raspodele izvršavanja kroz shardove.

Ista arhitektura koja donosi skalabilnost zahteva od developera da ozbiljno razmišlja o parcijalnom uspehu, redosledu događaja i lokalnoj konzistentnosti.

TON zato nije težak zato što ima mnogo neobičnih termina. Težak je onda kada se pokušava programirati kao sistem koji nije.

Kada se contract posmatra kao state machine, poruka kao događaj, trace kao distribuirani workflow, a backend kao verifikator i projekcija blockchain stanja, TON postaje znatno razumljiviji.

Sponzorstvo

Ovaj članak je sponzorisan od strane Volet.com. Na Volet.com možete kupiti, prodati, čuvati i razmenjivati podržane kriptovalute i fiat valute.

Više informacija dostupno je na stranici Volet Srbija.

Za otvaranje naloga možete koristiti Volet.com pozivni link.