TronWeb Giới thiệu: SDK JavaScript cho TRON Blockchain

TronWeb là SDK JavaScript chính để phát triển TRON — tương tự như ethers.js trên Ethereum. Nó xử lý mã hóa địa chỉ, xây dựng giao dịch, gọi hợp đồng thông minh và tích hợp ví cho dApp, chương trình phụ trợ và tập lệnh.

Phần giới thiệu này đề cập đến việc cài đặt, cấu hình, các khái niệm cốt lõi và quá trình chuyển TRX đầu tiên của bạn từ mã.

Khi nào nên sử dụng TronWeb

Sử dụng TronWeb khi bạn cần:

• Xây dựng dApp web kết nối với TronLink hoặc sử dụng các khóa được nhúng
• Chạy các dịch vụ phụ trợ gửi USDT hoặc kích hoạt hợp đồng
• Triển khai và tương tác với các hợp đồng TRC-20 / Solidity
• Đăng ký các sự kiện (có bỏ phiếu hoặc tiện ích mở rộng)

Để truy cập HTTP thuần túy mà không cần trừu tượng hóa SDK, hãy xem TronGrid Hướng dẫn API và Tham khảo API HTTP.

Cài đặt

npm install tronweb

Trình duyệt: gói qua webpack/vite hoặc tải từ CDN cho các nguyên mẫu (thích npm để sản xuất).

Thiết lập cơ bản

Chỉ đọc (không có khóa riêng)

const TronWeb = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': 'your-api-key' },
});

Nhận khóa API từ TronGrid.

Với khóa ký (chỉ phía máy chủ)

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: process.env.TRON_PRIVATE_KEY,
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
});

Mạng thử nghiệm Shasta

const tronWeb = new TronWeb({
  fullHost: 'https://api.shasta.trongrid.io',
  privateKey: 'your-shasta-test-key',
});

Nhận Shasta TRX miễn phí từ các vòi để thử nghiệm TRC-20 triển khai.

Đối tượng cốt lõi

Ví dụ gửi TRX

async function sendTrx(toAddress, amountTrx) {
  const amountSun = tronWeb.toSun(amountTrx);
  const tx = await tronWeb.trx.sendTransaction(toAddress, amountSun);
  return tx;
}

Theo dõi xác nhận bằng xác minh API giao dịch.

Tương tác ## TRC-20 {#trc20}

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

async function getUsdtBalance(address) {
  const contract = await tronWeb.contract().at(USDT);
  const balance = await contract.balanceOf(address).call();
  return tronWeb.toBigNumber(balance).div(1e6).toString();
}

Tìm hiểu sâu: truy vấn TRC-20 Balance và gửi USDT theo chương trình.

Tích hợp ## TronLink (trình duyệt) {#tronlink}

async function getTronWeb() {
  if (window.tronLink && window.tronLink.ready) {
    return window.tronLink.tronWeb;
  }
  throw new Error('TronLink not found');
}

Người dùng ký các giao dịch trong cửa sổ bật lên của ví — trang web của bạn không bao giờ nhìn thấy khóa riêng.

Xử lý lỗi

Các hư hỏng thường gặp:

• OUT_OF_ENERGY — tài khoản cần TRX hoặc Năng lượng bị đóng băng
• REVERT — cuộc gọi bị từ chối hợp đồng thông minh
• Địa chỉ không hợp lệ — luôn tronWeb.isAddress() trước khi gửi

Ánh xạ tới các thông báo thân thiện với người dùng trong ứng dụng sản xuất.

Mẹo về cấu trúc dự án

• Riêng phiên bản TronWeb chỉ đọc cho các truy vấn công khai
• Mô-đun người ký bị cô lập trên máy chủ có bí mật HSM hoặc env
• Giới hạn tốc độ cuộc gọi TronGrid; số khối bộ đệm
• Sử dụng trình nghe sự kiện để phát hiện tiền gửi

Bảo mật {#bảo mật}

• Bảo mật hợp đồng thông minh
• Xác thực tất cả các địa chỉ do người dùng cung cấp
• Không bao giờ đăng nhập khóa riêng
• Mô phỏng các cuộc gọi hợp đồng khi có thể trước khi gửi mạng chính

TronWeb so với các SDK khác

Các nhà phát triển Python sử dụng tronpy; Các đội đi sử dụng gotron-sdk. TronWeb vẫn là tài liệu được ghi chép nhiều nhất về dApps của trình duyệt và chương trình phụ trợ Node.js. Chọn dựa trên ngăn xếp của bạn — chuyển các khái niệm (mã hóa địa chỉ, ký tên, ABI) qua các thư viện.

Biến môi trường và bí mật

Không bao giờ cam kết khóa riêng. Sử dụng các tệp .env bị loại trừ khỏi git hoặc trình quản lý bí mật trên đám mây trong quá trình sản xuất. Phiên bản TronWeb trên máy chủ nên sử dụng ví nóng chuyên dụng với số dư tối thiểu — quét vào kho lạnh. Xoay phím nếu nhật ký có thể đã ghi lại kết xuất môi trường.

Danh sách kiểm tra khắc phục sự cố

Nếu có sự cố xảy ra trên TRON, hãy xử lý nó như một vấn đề gỡ lỗi có cấu trúc: xác nhận txid chính xác trên chuỗi, xác minh địa chỉ hợp đồng mục tiêu và chỉ sau đó mới quyết định xem liệu lỗi có thể phục hồi được hay không. Trên TRON, nhiều vấn đề “bí ẩn” chỉ đơn giản là một trong số: mạng sai (mainnet so với testnet), hợp đồng mã thông báo sai (USDT giả / mã thông báo có tên tương tự), không đủ tài nguyên (OUT_OF_ENERGY / băng thông) hoặc độ trễ giao diện người dùng/trình lập chỉ mục giữa ví và trình khám phá.

Bắt đầu với các bước kiểm tra dựa trên chuỗi sau:

• Luôn sao chép toàn bộ txid/hash từ ví hoặc explorer của bạn.
• Xác nhận trạng thái kết quả tx trên TronScan (SUCCESS, REVERT, OUT_OF_ENERGY hoặc vẫn đang chờ xử lý).
• Kiểm tra xem địa chỉ người nhận/hợp đồng có khớp với nội dung bạn định gửi hay không.
• Nếu đó là lệnh gọi hợp đồng, hãy xác nhận rằng bộ chọn chức năng và các tham số phù hợp với tiêu chuẩn mã thông báo mà bạn cho rằng mình đang sử dụng (TRC-20 so với TRC-10 so với BEP-20 trên BSC).

Sau đó áp dụng đường dẫn sửa lỗi cho danh mục của bạn:

• Xác nhận trạng thái và thông số giao dịch.
• Xác minh địa chỉ (hợp đồng mã thông báo, người nhận, bộ định tuyến/người chi tiêu).
• Thêm hoặc ủy quyền tài nguyên (Năng lượng/Băng thông) khi lỗi do tài nguyên.

###Những lỗi thường gặp

Các mẫu này gây ra hầu hết các lỗi ở cấp độ người dùng:

• Sử dụng địa chỉ mainnet trên testnet (hoặc ngược lại).
• Sao chép ký hiệu mã thông báo thay vì địa chỉ hợp đồng TRC-20 thực tế.
• Ký sai địa chỉ phê duyệt/chi tiêu do liên kết UI độc hại hoặc lỗi thời.
• Thử lại mà không thay đổi đầu vào bị lỗi (ví dụ: REVERT tiếp tục hoàn nguyên cho đến khi bạn sửa được tham số).

Nếu bạn không chắc chắn, đừng “gửi lại”. Thực hiện một thay đổi có kiểm soát, xác minh trên TronScan rồi tiếp tục.

##Câu hỏi thường gặp

Làm cách nào để biết liệu giao dịch có thực sự được xác nhận hay không?

Sử dụng TronScan và kiểm tra trạng thái kết quả tx. Nhãn “đang chờ xử lý” của ví có thể bị trễ; trạng thái dây chuyền là nguồn gốc của sự thật. Sao chép txid và xác minh SUCCESS/REVERT/OUT_OF_ENERGY, không chỉ văn bản giao diện người dùng.

Tại sao giao diện người dùng khác với TronScan?

Một số ví và dApp sử dụng các bộ chỉ mục hoặc lớp bộ đệm khác nhau. Độ trễ ngắn giữa phát sóng và lập chỉ mục là bình thường; so sánh txid và đợi chuỗi ổn định trước khi kết luận thất bại.

Tôi nên làm gì sau REVERT?Dừng và giải mã cuộc gọi thất bại. Hầu hết REVERT đều do tham số không hợp lệ, địa chỉ hợp đồng sai, thiếu phê duyệt hoặc không khớp giữa tiêu chuẩn và phương thức mã thông báo. Khắc phục nguyên nhân rồi ký lại.

Ký phê duyệt không giới hạn có an toàn không?

Phê duyệt không giới hạn chỉ an toàn đối với các địa chỉ chi tiêu đáng tin cậy mà bạn đã xác minh (nguồn đã xác minh, bộ định tuyến chính xác và hợp đồng mã thông báo dự kiến). Để thử nghiệm, hãy ưu tiên phê duyệt có giới hạn và thu hồi sau khi bạn hoàn thành.

TRON yêu cầu những tài nguyên gì cho các cuộc gọi hợp đồng?

Việc thực thi hợp đồng thông minh chủ yếu tiêu thụ Năng lượng, trong khi byte giao dịch tiêu thụ Băng thông. Nếu bạn nhận được OUT_OF_ENERGY, hãy thêm/đóng băng/ủy thác Năng lượng. Nếu băng thông cạn kiệt, hãy tập trung vào việc giữ đủ chất lỏng TRX để phân bổ byte và tài nguyên.

Làm cách nào để giảm phiếu hỗ trợ?

Hiển thị cho người dùng thông báo rõ ràng về “điều gì đã xảy ra” dựa trên trạng thái chuỗi và liên kết trực tiếp đến hướng dẫn có liên quan (đang chờ xử lý, không thành công, hết năng lượng hoặc xác minh). Lưu trữ txid để bạn có thể hòa giải nhanh chóng.

Hướng dẫn liên quan {#có liên quan}

• TronGrid Hướng dẫn API
• Kích hoạt hợp đồng thông minh
• TRON Tham khảo API HTTP
• Triển khai TRC-20 TronWeb

Câu hỏi thường gặp

TronWeb là gì?

TronWeb là thư viện JavaScript chính thức để tương tác với chuỗi khối TRON — tài khoản, hợp đồng, giao dịch và truy vấn từ Node.js hoặc ứng dụng trình duyệt.

Tôi có cần khóa riêng để đọc dữ liệu blockchain không?

Không. Các hoạt động chỉ đọc như truy vấn số dư hoạt động với nút đầy đủ công khai hoặc khóa API TronGrid mà không làm lộ khóa riêng tư.

TronWeb vs TronGrid?

TronGrid là cơ sở hạ tầng API được lưu trữ. TronWeb là SDK khách giao tiếp với TronGrid hoặc nút đầy đủ của riêng bạn.

TronWeb có ​​hỗ trợ TypeScript không?

Sử dụng các gói cộng đồng @types hoặc các loại đi kèm của TronWeb nếu có. Gói cuộc gọi hợp đồng với giao diện đã nhập trong mã ứng dụng.

Tôi nên sử dụng phiên bản nào?

Ghim bản ổn định mới nhất từ ​​​​npm và thử nghiệm trên Shasta trước khi triển khai mạng chính.