{"id":25394945,"url":"https://github.com/zeta-chain/protocol-contracts-ton","last_synced_at":"2025-10-30T20:30:25.457Z","repository":{"id":255203238,"uuid":"844951878","full_name":"zeta-chain/protocol-contracts-ton","owner":"zeta-chain","description":"ZetaChain Gateway for TON blockchain","archived":false,"fork":false,"pushed_at":"2024-11-05T10:32:06.000Z","size":225,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-05T11:38:06.665Z","etag":null,"topics":["blockchain","cross-chain","func","ton","tvm"],"latest_commit_sha":null,"homepage":"https://zetachain.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeta-chain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-20T09:38:21.000Z","updated_at":"2024-11-04T11:09:59.000Z","dependencies_parsed_at":"2024-11-05T11:30:23.960Z","dependency_job_id":null,"html_url":"https://github.com/zeta-chain/protocol-contracts-ton","commit_stats":null,"previous_names":["zeta-chain/protocol-contracts-ton"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeta-chain%2Fprotocol-contracts-ton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeta-chain%2Fprotocol-contracts-ton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeta-chain%2Fprotocol-contracts-ton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeta-chain%2Fprotocol-contracts-ton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeta-chain","download_url":"https://codeload.github.com/zeta-chain/protocol-contracts-ton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239048257,"owners_count":19573187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cross-chain","func","ton","tvm"],"created_at":"2025-02-15T19:52:31.516Z","updated_at":"2025-10-30T20:30:25.444Z","avatar_url":"https://github.com/zeta-chain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zetachain Protocol Contracts for TON\n\nThis repo contains **Gateway** implementation that brings cross-chain capabilities to The Open Network by leveraging Zetachain's Universal Apps. \n\n## Learn more about ZetaChain\n\n* Check our [website](https://www.zetachain.com/)\n* Read our [docs](https://docs.zetachain.com/)\n\n## Supported user operations\n\n| Op      | Name               | Description                                                        |\n|---------|--------------------|--------------------------------------------------------------------|\n| 100     | `donate`           | Donate TON to the Gateway :)                                       |\n| 101     | `deposit`          | Deposit TON to a recipient on Zeta EVM                             |\n| 102     | `deposit_and_call` | Deposits TON to Zeta EVM and call a contract with `call_data`      |\n| 103     | `call`             | Trigger `onCall` on Zeta EVM contract with specified `call_data`   |\n\n\nWithdraw operations are initiated by invoking `Gateway.withdraw(...)` in Zetachain.\nCheck out our docs for further reference!\n\n[Contracts Documentation](./docs/gateway.md) (codegen)\n\n## Project structure\n\nThe project is built using [Blueprint](https://github.com/ton-org/blueprint).\n\n- `contracts` - FunC contracts source code\n- `types` - TS types \u0026 (de)serialization utils\n- `wrappers` - TS wrappers for ease of interacting with gateway\n- `tests` - tests for the contracts.\n- `scripts` - Blueprint scripts with various tasks\n\n## How to use\n\n- `make compile` compiles all smart contracts;\n- `make test` executes the unit tests for the contracts;\n- `make deploy` deploys the Gateway;\n- `make tx` sends various messages to the contract;\n- `make help` shows all available cli commands including upgrade \u0026 authority operations\n\n## Localnet\n\nThis project is integrated with Zeta's [localnet](https://github.com/zeta-chain/localnet). It essentially allows developers to write cross-chain apps between EVM, SOL, TON, and more with full end-to-end testing **locally**\n\nYou can send transactions directly to localnet's Gateway by calling `make tx-localnet`. Note that most TON wallets don't support custom networks, so the mnemonic is used for dev purposes *only*\n\n```sh\nexport WALLET_VERSION=\"V5R1\" # or other version\nexport WALLET_MNEMONIC=\"front local amused plastic ...\"\n\nmake tx-localnet\n```\n\nTip: to generate a wallet on localnet use the following command (in localnet's repo)\n\n```sh\nyarn localnet ton wallet\n```\n\n## How it works\n\nAll inbound operations (deposit, call, ...) are represented as internal messages that have the following structure:\n\n- uint32 `op_code` - operation code. Standard for TON\n- uint64 `query_id` - not used right now. Standard for TON\n- ... the rest of the message is the operation-specific data\n\nUse `types` package for encoding/decoding data to BoC.\n\nExample `deposit` message schema:\n\n```\nop_code:uint32 query_id:uint64 evm_recipient:slice (160 bits / 20 bytes)\n```\n\n### Gas usage\n\nDue to nature of TON, we use gas \"ceiling\" approach where we assume that each op has a const \"max cost\" that we subtract from the caller. you can call the `int calculate_gas_fee(int op) method_id` getter to receive a fee in nanoTON. \n\nExample: to send 1 TON to Zeta recipient `0x873F092B7598D1B2BEa4F21C7f3b86b9e8f6e7e4`, you actually need to send 1 TON + calculate_gas_fee(101), where 101 is the op code for the deposit operation.\n\n\n### Withdrawals\n\n\u003e All withdrawals are triggered by Zeta EVM, developers don't need to worry about these technical nuances.\n\nZetaChain uses MPC (Multi Party Computation) to sign all outbound transactions using TSS (Threshold Signature Scheme).\n\nDue to the technical implementation TSS uses ECDSA cryptography in opposite to EdDSA in TON.\nThus, the contract must verify ECDSA signatures directly on-chain.\n\nAll TSS commands are represented as external messages that have the following structure:\n\n- `[65]byte signature` - ECDSA signature of the message hash (v, r, s)\n- `cell ref payload` - Message payload\n    - `uint32 op_code` - operation code\n    - the rest of the payload is the operation-specific data...\n\nBy having this structure we can sign arbitrary messages using ECDSA, recover signature,\nthen ensure sender and proceed with the operation.\n\nThe payload for `op withdrawal (200)` is the following:\n\n```\nop:uint32 recipient:MsgAddr amount:Coins seqno:uint32\n```\n\nExternal message signature flow:\n\n1. Calculate the hash of the payload cell: `payload_hash` = `sha256(payload_data)`\n2. Recover ECDSA public key from the signature. Derive sender's EVM address from the public key.\n3. Check that the message comes from TSS address.\n4. Route the payload to the corresponding operation code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeta-chain%2Fprotocol-contracts-ton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeta-chain%2Fprotocol-contracts-ton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeta-chain%2Fprotocol-contracts-ton/lists"}