inkathon
@inkathon
Ini adalah boilerplate dapp penuh tumpukan untuk tinta! Kontrak pintar dengan frontend terintegrasi. Ini dapat digunakan untuk dengan cepat mulai mengembangkan ide hackathon Anda atau untuk perancah aplikasi Web3 siap-produksi.
Proyek ini merupakan bagian dari inisiatif Scio Labs untuk meningkatkan pengalaman pengembang dengan tinta! Ekosistem dan anggota yang bangga dari Aleph Zero EFP. ?
Proyek lain termasuk:
create-ink-app cli ( segera hadir )ink!athon BoilerplateuseInkathon Hooks & Utility Libraryzink! Makro Kontrak CerdasBergabunglah dengan diskusi di grup telegram kami
Jika Anda ingin berkontribusi, silakan baca pedoman kontributor kami
Daftar isi:
Boilerplate hadir dengan tinta sampel kecil! Kontrak Greeter yang menyimpan message ("salam") dan memungkinkan siapa saja untuk memperbaruinya. Frontend berisi komponen UI sederhana untuk menghubungkan dompet Anda dan berinteraksi dengan kontrak (yaitu membaca & menulis message ). Cobalah langsung di Inkathon.xyz.
Frontend bekerja di luar kotak, tanpa simpul lokal berjalan, karena kontrak sampel telah dikerahkan sebelumnya pada testnet hidup tertentu (yaitu alephzero-testnet dan shibuya ). Metadata dan alamat penyebaran yang diperlukan disediakan berdasarkan contracts/deployments/ .
Prasyarat:
- Setup Node.js V18+ (Direkomendasikan melalui NVM dengan
nvm install 18)- Instal PNPM (disarankan melalui node.js corePack atau
npm i -g pnpm)- Kloning repositori ini
[!PENTING]
Pengguna Windows harus menggunakan WSL (disarankan) atau shell khusus seperti Git Bash. PowerShell tidak didukung.
Prasyarat saat menggunakan WSL untuk Linux:
- Instal WSL dan jalankan semua perintah di terminal WSL
- Setup Node.js V18+ (Direkomendasikan melalui NVM dengan
nvm install 18)- Instal Paket NPM berikut secara global:
npm i -g npmnpm i -g pnpm node-gyp make- Kloning repositori ini ke dalam sistem file WSL (misalnya
/home/<user>/inkathon).Kiat: Anda dapat memasukkan
\wsl$di bilah atas Windows Explorer untuk mengakses sistem file WSL secara visual.
# Install dependencies (once)
# NOTE: This automatically creates an `.env.local` file
pnpm install
# Start Next.js frontend
pnpm run dev Secara opsional, untuk mengaktifkan simple-git-hooks (untuk linting & format otomatis saat berkomitmen), Anda dapat menjalankan perintah berikut sekali: pnpm simple-git-hooks .
File contracts/package.json berisi skrip steno untuk membangun, menguji, dan menggunakan kontrak Anda.
Prasyarat:
- Instal Rust melalui Dokumen Substrat (Lewati bagian "Kompilasi Node Substrat")
- Pasang
cargo contract- Instal
substrate-contracts-node
# Set `contracts/` as the active working directory in your terminal
cd contracts
# Build contracts and move artifacts to `contracts/deployments/{contract}/` folders
pnpm run build
# Start local node with persistence (contracts stay deployed after restart)
# NOTE: When using Brave, shields have to be taken down for the UIs
pnpm run node
# # IMPORTANT: Open a separate terminal window and keep the node running
# Deploy the contracts on the local node
pnpm run deploy Atau, Anda juga dapat menggunakan kontrak secara manual menggunakan kontrak UI ( pnpm contracts-ui ) di browser.
Buka file frontend/.env.local dan atur variabel NEXT_PUBLIC_DEFAULT_CHAIN ke development . Kemudian restart frontend dan Anda harus dapat berinteraksi dengan kontrak yang digunakan pada simpul lokal Anda.
Baca lebih lanjut tentang variabel lingkungan dan semua konstanta rantai yang tersedia di bagian Variabel Lingkungan di bawah ini.
Ada beberapa tempat di mana Anda perlu memasukkan nama dan pengidentifikasi proyek Anda. Sebagian besar kejadian ini disorot dengan a /* TODO */ komentar dalam kode. Anda dapat dengan mudah menggantinya satu per satu dengan memasang plugin todo-tree .
Selain itu, ada kejadian yang tidak terasa sangat besar:
inkathon.code-workspacepackage.json di direktori root serta dalam contracts/ dan frontend/ paket@inkathon/contracts ) yang didefinisikan di frontend/package.json dan diimpor di frontend/src/deployments/deployments.ts Untuk mengganti kontrak Greeter default atau menambahkan yang baru, Anda perlu melakukan hal berikut:
contracts/src/contracts/Cargo.tomlcontracts/scripts/deploy.tsgetDeployments ContractIds di frontend/src/deployments/deployments.ts Menambahkan skrip khusus berguna untuk berinteraksi dengan kontrak Anda atau menguji fungsionalitas tertentu. Oleh karena itu, cukup duplikat & gunakan kembali file contracts/scripts/script.template.ts dan jalankan melalui pnpm run script <script-name> . Perintah ini akan menjalankan file TypeScript secara langsung melalui tsx .
Untuk skrip umum, inisialisasi & konfigurasi variabel lingkungan yang sama berlaku seperti yang dijelaskan di bawah ini di bagian penyebaran (misalnya untuk mengubah jaringan target).
contracts/ dan frontend/ direktori sebagai paket.pnpm atau yarn@stable (Baca lebih lanjut di bagian FAQ di bawah)cargo-contract , substrate-contracts-nodepolkadot-js , useInkathon React Hooks & Utility Library (Atau: useInk )shadcn/ui , tailwindcsseslint , prettier , simple-git-hooks , lint-stagedtypechain-polkadotPerpustakaan penataan, linting, dan format dapat dijatuhkan atau diganti dengan alternatif.
Di bawah ini Anda menemukan contoh langsung yang menggunakan boilerplate ini atau memiliki pengaturan serupa yang terinspirasi olehnya:
Memutar penempatan melalui Vercel cukup mudah karena pengaturan yang diperlukan sudah dikonfigurasi di vercel.json . Jika Anda belum mengkloning repositori, Anda juga dapat menggunakan tombol Deploy di bawah ini untuk membuat repositori baru dari templat ini.
Atau, Anda juga dapat menggunakan dockerfile yang disediakan untuk digunakan ke penyedia hosting pilihan Anda. Baca lebih lanjut di sini.
Semua variabel lingkungan diimpor dari process.env di frontend/src/config/environment.ts dan diekspor kembali dari sana. Untuk keamanan tipe yang lebih baik, selalu hanya mengimpor variabel lingkungan dari @/config/environment dan tidak pernah langsung dari process.env .
| Variabel Lingkungan | Nilai default | Keterangan |
|---|---|---|
NEXT_PUBLIC_DEFAULT_CHAIN *️⃣ | ️ alephzero-testnet | Jaringan (rantai berbasis substrat) Frontend harus terhubung secara default dan artefak penyebaran kontrak apa yang akan diimpor. |
NEXT_PUBLIC_PRODUCTION_MODE | false | Bendera boolean opsional untuk membedakan lingkungan produksi (misalnya untuk SEO atau analitik). |
NEXT_PUBLIC_URL | http://localhost:3000 | String opsional yang mendefinisikan URL dasar frontend (akan diterapkan secara otomatis dari variabel lingkungan Vercel). |
NEXT_PUBLIC_SUPPORTED_CHAINS | - - | Array opsional dengan pengidentifikasi jaringan (misalnya ["alephzero-testnet", "shibuya"] ) yang didukung oleh frontend, jika DAPP seharusnya multi-rantai . |
*️⃣ diperlukan
Salah satu elemen kunci yang membuat boilerplate ini begitu fleksibel adalah penggunaan variabel lingkungan untuk mengonfigurasi jaringan aktif di frontend. Ini dilakukan dengan mengatur variabel NEXT_PUBLIC_DEFAULT_CHAIN di file frontend/.env.local , atau masing -masing dalam pengaturan penyebaran.
Jika jaringan Anda tidak disediakan oleh Pustaka use-inkathon , Anda dapat menambahkannya secara manual dengan membuat objek SubstrateChain baru. Jika Anda berpikir rantai hilang, buka masalah atau PR.
Penting
Semua konstanta rantai yang didukung dapat ditemukan di sini di repositori scio-labs/use-inkathon .
Di bagian pemula di atas, kami telah menggunakan kontrak Greeter sampel pada simpul lokal. Untuk menargetkan jaringan langsung, kita dapat menggunakan variabel lingkungan CHAIN saat menjalankan skrip deploy .
CHAIN=alephzero-testnet pnpm run deploy Selanjutnya, file lingkungan yang dimuat secara dinamis dengan .env.{chain} penamaan konvensi dapat digunakan untuk menambahkan konfigurasi tambahan tentang akun Deployer.
# .env.alephzero-testnet
ACCOUNT_URI=bottom drive obey lake curtain smoke basket hold race lonely fit walk//AliceSaat menjalankan skrip yang sama lagi, akun penggalian ini didefinisikan di sana akan digunakan untuk menandatangani ekstrinsik.
Peringatan
File -file ini di -gitgnored secara default, tetapi Anda harus tetap sangat berhati -hati saat menambahkan informasi sensitif kepada mereka.
Dapat membantu untuk dikembangkan di vScode dengan membuka file workspace inkathon.code-workspace bukan hanya direktori polos. Pendekatan ini menawarkan banyak keunggulan, seperti bagian dalam file explorer, atau tindakan jalan pintas untuk membuka terminal di direktori yang benar.
Pertimbangkan untuk menginstal ekstensi zoma.vscode-auto-open-workspace untuk secara otomatis membuka file ruang kerja saat membuka direktori.
Selain itu, plugin vScode yang tercantum di bawah ini disarankan karena dapat sangat membantu saat bekerja dengan boilerplate ini.
| Nama plugin | Keterangan |
|---|---|
dbaeumer.vscode-eslint | Menambahkan dukungan editor Eslint. |
esbenp.prettier-vscode | Menambahkan dukungan editor yang lebih cantik. |
bradlc.vscode-tailwindcss | Menambahkan Dukungan Editor TailwindCSS. |
rust-lang.rust-analyzer | Menambahkan dukungan bahasa karat. |
ink-analyzer.ink-analyzer | Menambahkan tinta! dukungan bahasa. |
tamasfe.even-better-toml | Menambahkan dukungan file .toml . |
gruntfuggly.todo-tree | Daftar semua komentar TODO di ruang kerja Anda. |
wayou.vscode-todo-highlight | Sorotan komentar TODO di ruang kerja Anda. |
mikestead.dotenv | Menambahkan sorotan sintaks untuk file .env . |
Minuman! CLI adalah alat baris perintah yang nyaman yang membantu Anda bermain dengan tinta Anda! Kontrak tanpa menyiapkan simpul lokal.
drink-cli melalui cargo install drink-cli --force --locked .pnpm run build .pnpm run drink-cli <contract-name> . Kemudian, cukup gunakan perintah help untuk melihat semua perintah yang tersedia dan mulai berinteraksi dengan kontrak Anda. Misalnya, Anda dapat menggunakan kontrak contoh penyambut melalui d --constructor default atau d "Hello World" .
Untuk ruang kerja monorepo, PNPM kemungkinan merupakan pilihan tercepat dan paling dapat diandalkan. Saat menggunakannya, sangat disarankan semua orang di tim menggunakannya. Tidak ada pemasangan yang harus dilakukan atau file kunci lainnya harus dilakukan.
Sebagai alternatif, benang juga didukung dan dapat digunakan untuk pemasangan. Peringatan saat menggunakan benang:
yarn.lock harus dilakukan alih-alih file .pnpm-lock.yaml .pnpm CLI masih digunakan dalam banyak package.json JKS. JKS, jadi ini harus disesuaikan secara manual.[!PENTING]
Karena NPM tidak memiliki dukungan untuk protokol imporworkspace, itu tidak kompatibel dengan Ink! Aton.
Terkadang, Next.js tidak mengambil perubahan (yaitu kreasi file) dalam contracts/deployments/{contract}/ folder dengan benar. Misalnya, ketika Anda baru saja digunakan pada simpul lokal untuk pertama kalinya dan mengatur .env.local frontend untuk terhubung ke jaringan development .
Untuk memperbaikinya, Anda dapat menghapus cache build di frontend/.next . Ini adalah satu -satunya solusi dan akan memaksa Next.js untuk membangun kembali proyek dan mengambil file baru.
[!CATATAN]
Untuk mencegah perilaku ini, filecontracts/package.jsonberisi skrippostinstallkecil yang membuat filedevelopment.tskosong jika tidak ada.
Saat ini ia menawarkan gaya melalui opsi berikut di luar kotak:
className dan *.module.(s)css .[! Info]
Boilerplate ini mencoba untuk tetap tidak diungkapkan dalam hal gaya, yang berarti Anda dapat menggunakan perpustakaan gaya atau komponen apa pun.
Dengan typechain-polkadot , tipe untuk setiap kontrak (file ncript) dibuat saat dibangun (melalui skrip build atau perintah build-all.sh ). Anda dapat menekan perilaku ini dengan lulus --skip-types .
Mereka disimpan di bawah contracts/typed-contracts/ dan diimpor langsung dari frontend. Kemudian, melalui Hook Kontrak useRegisteredTypedContract baru dari contoh useInkathon dengan API yang telah ditentukan, alamat kontrak yang bergantung pada jaringan, dan penandatangan yang disuntikkan sedang dibuat. Lihat Contoh greeter-contract-interactions.tsx .
