sunsail

README

SunSail A minimalist, ultra-fast smart-contract development framework for the TRON network, written entirely in Go. One static binary — sun — replaces the JavaScript tooling with a Foundry-inspired workflow: compilation, Solidity-native testing on a real TVM interpreter, deployment scripting with exact costs, energy estimation against live network state, and security auditing.

License: Apache-2.0.

Why

• One binary, zero runtime dependencies. CGO_ENABLED=0, statically linked, cross-compiled for linux/darwin/windows. No Node, no npm. Windows builds are cross-compiled and unit-tested but not CI-executed (see docs/CI.md).
• A real TVM, not an EVM approximation. The built-in interpreter implements TRON's divergences — the two-layer energy model, TRON's SSTORE pricing, the exact precompile transforms, 0x41 address derivation, call depth 64, TIP-6780 — and its metering is validated ±0 against java-tron on Nile (no tolerances; see docs/TVM.md).
• Real transactions, not simulations. On TRON a deployment address derives from the transaction id, so sun script builds the actual signed transaction sequence — tx N's txid feeds tx N+1's addresses — and the planned costs equal the on-chain receipts exactly.
• Trust through verification. External binaries (solc-tron, aderyn) are version-pinned and SHA-256-verified before they ever execute. Where the node contradicts the documentation, the node wins and the discrepancy is recorded (see the Errata section of docs/ARCHITECTURE.md).

Install

With Go 1.26+ installed, the fastest path is go install:

go install github.com/sailor-labs/sunsail/cmd/sun@latest

Or grab a prebuilt static binary for your platform from the Releases page (available since v0.1.0; verify it against the published SHA256SUMS).

Or build from source (requires Go 1.26+):

git clone https://github.com/sailor-labs/sunsail
cd sunsail
make build            # ./out/sun for the host platform
make release          # 6-platform static matrix + SHA256SUMS

Commands

Command	What it does	Example
sun init	Scaffold a Foundry-like project from embedded templates	sun init my-project
sun compile	Incremental, deterministic compilation with a pinned solc-tron	sun compile
sun test	Run Solidity tests (test/*.t.sol) on the local TVM, with cheatcodes and source-mapped traces; optionally over the live state of a network	sun test -vvv --fork-url nile
sun estimate	Exact Energy / Bandwidth / TRX-burn figures for a call to an already-deployed contract	sun estimate TMts7FK5h5US99x16qCRkJUzd1VYtahd7o "sail(uint256)" 5 --network nile
sun script	Plan (and optionally broadcast) a deployment script as a real transaction sequence with per-tx costs	sun script script/Deploy.s.sol --network nile --broadcast
sun audit	Aderyn static analysis with TVM-aware per-file degradation	sun audit --fail-on high
sun sonar	Utilities: address conversion, selectors, CREATE2 derivation	sun sonar address TR7NHq...

sun estimate reports the cost of calling a contract that is already deployed on the network — it needs the contract's on-chain address. To estimate a call to your own contract, deploy it first (e.g. with sun script --broadcast), then pass its address.

The typical end-to-end flow:

sun init dapp && cd dapp
sun compile
sun test -v
sun script script/Deploy.s.sol --network nile --broadcast   # deploy first
sun estimate <deployed-address> "sail(uint256)" 5 --network nile
sun audit

Naming, quickly

• sun is the binary (TRX's smallest unit is also called sun — that is the pun, embrace it).
• sail.toml is the project configuration: pinned compiler + checksums, network endpoints, the audit binary pin. See docs/CONFIG.md.
• sail.sol is the embedded cheatcode interface available to tests (sail.prank(...), sail.deal(...), sail.expectRevert(), ...). See docs/TESTING.md.

Networks

sail.toml declares each network's three endpoints — the FullNode gRPC service (broadcast), the Solidity gRPC service (irreversible confirmation), and a JSON-RPC endpoint used only by the fork storage reader. The scaffold ships mainnet and nile (the public test network) preconfigured. Develop against Nile first; sun script requires an explicit --broadcast before anything leaves your machine, and the signing key is only ever read from the PRIVATE_KEY environment variable or the project's git-ignored .env.

Documentation

Deep references live in docs/:

• ARCHITECTURE.md — the source of truth: design, invariants, audit adjudications, and the errata log (E1–E5).
• CONFIG.md — sail.toml schema and project layout.
• COMPILER.md — the compilation pipeline and binary management.
• TESTING.md — the test runner, cheatcodes, traces.
• FORKING.md — the pinned-fork backend (sun test --fork-url).
• SCRIPTING.md — the plan/broadcast model of sun script.
• AUDIT.md — the audit pipeline and its TVM post-filter.
• TVM.md — interpreter divergences, precompiles, energy model, and the differential validation results.
• RPC.md / CRYPTO.md / BUILD.md — networking, signing, and build contracts.
• CI.md — the three GitHub Actions workflows and the secrets the nightly needs.

Contributions welcome — see CONTRIBUTING.md. Security reports: SECURITY.md. Release history: CHANGELOG.md.