inkathon

هذا هو الكامل dapp boilerplate للحبر! العقود الذكية مع الواجهة الأمامية المتكاملة. يمكن استخدامه للبدء بسرعة في تطوير فكرة Hackathon أو سقالة تطبيق Web3 جاهز للإنتاج.

المشروع جزء من مبادرة Scio Labs لتحسين تجربة المطور في الحبر! النظام البيئي وعضو فخور في Aleph Zero EFP. ؟

تشمل المشاريع الأخرى:

• create-ink-app CLI ( قريبا )
• ink!athon غلاية
• useInkathon Hooks & Utility Library
• zink! وحدات الماكرو العقد الذكي

انضم إلى المناقشة في مجموعة Telegram الخاصة بنا

إذا كنت ترغب في المساهمة ، يرجى قراءة إرشادات المساهمين لدينا

---

جدول المحتويات:

1. عن
2. ابدء
   1. 1. قم بتشغيل الواجهة الأمامية
   2. 2. بناء ونشر العقود على عقدة محلية
   3. 3. قم بتوصيل الواجهة الأمامية بالعقدة المحلية
3. التخصيص؟
   1. 1. اسم المشروع
   2. 2. العقود المخصصة
   3. 3. البرامج النصية المخصصة
4. المكدس؟
5. أمثلة حية
6. النشر؟
   1. متغيرات البيئة
   2. نشر العقد
7. إعداد VScode؟
   1. مساحة العمل
   2. الإضافات
8. شرب! استخدام CLI؟
9. الأسئلة الشائعة واستكشاف الأخطاء وإصلاحها

---

عن

يأتي Boilerplate مع حبر عينة صغير! Greeter Contract التي تخزن message ("التحية") وتسمح لأي شخص بتحديثها. تحتوي الواجهة الأمامية على مكونات واجهة المستخدم البسيطة لتوصيل محفظتك والتفاعل مع العقد (أي قراءة وكتابة message ). جربها على الهواء مباشرة على inkathon.xyz.

ابدء

1. قم بتشغيل الواجهة الأمامية

تعمل الواجهة الأمامية خارج الصندوق ، دون تشغيل عقدة محلية ، حيث يتم نشر عقد العينة مسبقًا على بعض testnets الحية (أي alephzero-testnet و shibuya ). يتم توفير بيانات تعريف النشر اللازمة والعناوين بموجب contracts/deployments/ .

المتطلبات المسبقة:

• الإعداد node.js v18+ (موصى به عبر NVM مع nvm install 18 )
• تثبيت PNPM (الموصى به عبر node.js corepack أو npm i -g pnpm )
• استنساخ هذا المستودع

إرشادات خاصة لمستخدمي Windows

[!مهم]
يجب على مستخدمي Windows إما استخدام WSL (الموصى به) أو قذيفة مخصصة مثل Git Bash. PowerShell غير مدعوم.

المتطلبات المسبقة عند استخدام WSL لـ Linux:

• تثبيت WSL وتنفيذ جميع الأوامر في محطة WSL
• الإعداد node.js v18+ (موصى به عبر NVM مع nvm install 18 )
• قم بتثبيت حزم NPM التالية على مستوى العالم:
• npm i -g npm
• npm i -g pnpm node-gyp make
• استنساخ هذا المستودع في نظام ملفات WSL (على سبيل المثال /home/<user>/inkathon ).

نصيحة: يمكنك إدخال \wsl$ في الشريط العلوي من مستكشف Windows للوصول إلى نظام ملفات WSL بصريًا.

 # Install dependencies (once)
# NOTE: This automatically creates an `.env.local` file
pnpm install

# Start Next.js frontend
pnpm run dev

اختياريا ، لتمكين simple-git-hooks (للبطانة التلقائية والتنسيق عند الالتزام) ، يمكنك تشغيل الأمر التالي مرة واحدة: pnpm simple-git-hooks .

2. بناء ونشر العقود على عقدة محلية

يحتوي ملف contracts/package.json .

المتطلبات المسبقة:

• تثبيت الصدأ عبر مستندات الركيزة (تخطي قسم "ترجمة عقدة الركيزة")
• تثبيت cargo contract
• تثبيت 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

بدلاً من ذلك ، يمكنك أيضًا نشر عقود باستخدام عقود UI ( pnpm contracts-ui ) في المتصفح.

3. قم بتوصيل الواجهة الأمامية بالعقدة المحلية

افتح ملف frontend/.env.local وقم بتعيين متغير NEXT_PUBLIC_DEFAULT_CHAIN development . ثم أعد تشغيل الواجهة الأمامية ويجب أن تكون قادرًا على التفاعل مع العقود التي تم نشرها على العقدة المحلية.

اقرأ المزيد حول متغيرات البيئة وجميع ثوابت السلسلة المتاحة في قسم متغيرات البيئة أدناه.

التخصيص؟

1. اسم المشروع

هناك أماكن متعددة تحتاج فيها إلى إدراج اسم مشروعك ومعرفه. يتم تسليط الضوء على معظم هذه الأحداث مع A /* TODO */ التعليق في الكود. يمكنك بسهولة استبدالها بواحدة عن طريق تثبيت البرنامج المساعد todo-tree .

بالإضافة إلى ذلك ، هناك الأحداث التالية غير المضيئة:

• اسم ملف inkathon.code-workspace
• اسم package.json وبيانات التعريف في الدليل الجذر وكذلك في contracts/ frontend/ الحزم
• تبعية مساحة العمل ( @inkathon/contracts ) المحددة في frontend/package.json frontend/src/deployments/deployments.ts

2. العقود المخصصة

لاستبدال عقد Greeter الافتراضي أو إضافة عقد جديد ، تحتاج إلى القيام بما يلي:

• إضافة دليل عقد جديد بموجب contracts/src/
• أضفها كعضو آخر في مساحة العمل إلى ملف contracts/Cargo.toml
• أضف نصيًا آخر للنشر أو ضبط contracts/scripts/deploy.ts
• اضبط دالة ContractIds و getDeployments في frontend/src/deployments/deployments.ts

3. البرامج النصية المخصصة

تعد إضافة البرامج النصية المخصصة مفيدة للتفاعل مع عقودك أو اختبار وظائف معينة. لذلك ، فقط تكرار وإعادة استخدام contracts/scripts/script.template.ts ملف وقم بتشغيله عبر pnpm run script <script-name> . سيقوم هذا الأمر بتشغيل ملف TypeScript مباشرة عبر tsx .

بالنسبة للبرامج النصية العامة ، ينطبق التهيئة والتكوين المتغيرة نفسها كما هو موضح أدناه في قسم النشر (على سبيل المثال لتغيير الشبكة المستهدفة).

المكدس؟

المكدس بالتفصيل

• مساحة عمل Monorepo مع contracts/ frontend/ الدلائل كحزم.
• مدير الحزمة: pnpm أو yarn@stable (اقرأ المزيد في قسم الأسئلة الشائعة أدناه)
• تطوير العقود الذكية: substrate-contracts-node cargo-contract الحبر!
• الواجهة الأمامية: next.js (APP-DIR) ، React ، TypeScript
  • تفاعلات العقد: polkadot-js ، مكتبة useInkathon React Hooks & Utility (بدلاً من ذلك: useInk )
  • التصميم: shadcn/ui ، tailwindcss
  • Linting & Tonforting: eslint ، prettier ، simple-git-hooks ، lint-staged
• توليد عقد آمن من النوع عبر typechain-polkadot

يمكن إسقاط أو استبدال التصميم والتصميم والتنسيق بالكامل أو استبدالها بالبدائل.

أمثلة حية

ستجد أدناه أمثلة حية تستخدم هذا الغلاية أو إعداد مستوحى منه:

• Inkathon.xyz - نشر العرض التجريبي المباشر لهذا الغلاية
• Azero.id - خدمة اسم المجال لـ Aleph Zero وما وراءها
• مشاريع متعددة Hackathon من Ethwarsaw و Hackonchain و Ethdam و Polkadot حبر! هاكاثون.

النشر؟

يعد تدوير النشر عبر Vercel واضحًا جدًا حيث تم تكوين الإعدادات اللازمة بالفعل في vercel.json . إذا لم تقم باستنساخ المستودع بعد ، فيمكنك أيضًا استخدام زر النشر أدناه لإنشاء مستودع جديد من هذا القالب.

بدلاً من ذلك ، يمكنك أيضًا استخدام Dockerfiles المقدمة للنشر في أي مزود استضافة من اختيارك. اقرأ المزيد هنا.

متغيرات البيئة

يتم استيراد جميع متغيرات البيئة frontend/src/config/environment.ts process.env . من أجل تحسين السلامة من النوع ، دائمًا ما يستورد متغيرات البيئة فقط من @/config/environment وليس مباشرة من process.env .

متغيرات البيئة	القيم الافتراضية	وصف
NEXT_PUBLIC_DEFAULT_CHAIN *⃣	️ alephzero-testnet	الشبكة (السلسلة القائمة على الركيزة) يجب أن تتصل الواجهة الأمامية بشكل افتراضي وما هي القطع الأثرية لنشر العقد للاستيراد.
NEXT_PUBLIC_PRODUCTION_MODE	false	علامة منطقية اختيارية للتمييز بين بيئة الإنتاج (على سبيل المثال لكبار المسئولين الاقتصاديين أو التحليلات).
NEXT_PUBLIC_URL	http://localhost:3000	السلسلة الاختيارية التي تحدد عنوان URL الأساسي للواجهة الأمامية (سيتم تقديمه تلقائيًا من متغيرات بيئة Vercel).
NEXT_PUBLIC_SUPPORTED_CHAINS	-	صفيف اختياري مع معرفات الشبكة (على سبيل المثال ["alephzero-testnet", "shibuya"] ) التي تدعمها الواجهة الأمامية ، إذا كان من المفترض أن تكون DAPP متعددة .

*⃣ مطلوب

السلاسل المدعومة

أحد العناصر الرئيسية التي تجعل هذا الغلاية مرنة للغاية هو استخدام متغيرات البيئة لتكوين الشبكة النشطة في الواجهة الأمامية. يتم ذلك عن طريق تعيين متغير NEXT_PUBLIC_DEFAULT_CHAIN في الملف frontend/.env.local ، أو في إعدادات النشر على التوالي.

إذا لم يتم توفير شبكتك من خلال مكتبة use-inkathon ، فيمكنك إضافتها يدويًا عن طريق إنشاء كائن SubstrateChain جديد. إذا كنت تعتقد أن سلسلة مفقودة ، فيرجى فتح مشكلة أو علاقات عامة.

مهم

يمكن العثور على جميع ثوابت السلسلة المدعومة هنا في مستودع scio-labs/use-inkathon .

نشر العقد

في قسم البدء أعلاه ، قمنا بالفعل بنشر عقد Greeter العينة على عقدة محلية. لاستهداف شبكة حية ، يمكننا استخدام متغير بيئة CHAIN عند تشغيل البرنامج النصي deploy .

CHAIN=alephzero-testnet pnpm run deploy

علاوة على ذلك ، يمكن استخدام ملفات البيئة المحملة ديناميكيًا مع .env.{chain} CANEDING Convention لإضافة تكوين إضافي حول حساب Deployer.

 # .env.alephzero-testnet
ACCOUNT_URI=bottom drive obey lake curtain smoke basket hold race lonely fit walk//Alice

عند تشغيل نفس البرنامج النصي مرة أخرى ، سيتم تحديد حساب Deployer هذا لتوقيع خارجية.

تحذير

يتم توضيح هذه الملفات افتراضيًا ، لكن يجب أن تكون حذرًا إضافيًا عند إضافة معلومات حساسة لهم.

إعداد VScode؟

مساحة العمل

قد يكون من المفيد تطوير في VSCode عن طريق فتح ملف مساحة العمل inkathon.code-workspace بدلاً من الدليل العادي فقط. يوفر هذا النهج مزايا متعددة ، مثل الأقسام في مستكشف الملفات ، أو إجراءات الاختصار لفتح المحطة في الدليل الصحيح.

ضع في اعتبارك تثبيت ملحق zoma.vscode-auto-open-workspace لفتح ملف مساحة العمل تلقائيًا عند فتح الدليل.

الإضافات

بالإضافة إلى ذلك ، ينصح المكونات الإضافية VSCODE المذكورة أدناه حيث يمكن أن تكون مفيدة للغاية عند العمل مع هذا الغلاية.

جميع الإضافات الموصى بها

اسم البرنامج المساعد	وصف
dbaeumer.vscode-eslint	يضيف دعم محرر ESLINT.
esbenp.prettier-vscode	يضيف دعم محرر أجمل.
bradlc.vscode-tailwindcss	يضيف دعم محرر TailwindCSS.
rust-lang.rust-analyzer	يضيف دعم لغة الصدأ.
ink-analyzer.ink-analyzer	يضيف الحبر! دعم اللغة.
tamasfe.even-better-toml	يضيف دعم ملف .toml .
gruntfuggly.todo-tree	يسرد جميع تعليقات TODO في مساحة العمل الخاصة بك.
wayou.vscode-todo-highlight	أبرز تعليقات TODO في مساحة العمل الخاصة بك.
mikestead.dotenv	يضيف بناء بناء الجملة لملفات .env .

شرب! استخدام CLI؟

الشراب! CLI هي أداة سطر أوامر مريحة تساعدك على اللعب بالحبر الخاص بك! العقود دون إعداد عقدة محلية.

1. قم بتثبيت drink-cli عبر cargo install drink-cli --force --locked .
2. قم ببناء عقودك عبر pnpm run build .
3. قم بتشغيل الأمر التالي لإعداد وفتح CLI لعقدك: pnpm run drink-cli <contract-name> .

بعد ذلك ، ما عليك سوى استخدام أمر help لرؤية جميع الأوامر المتاحة والبدء في التفاعل مع عقدك. على سبيل المثال ، يمكنك نشر عقد Meether Example عبر d --constructor default أو d "Hello World" .

الأسئلة الشائعة واستكشاف الأخطاء وإصلاحها

أي مديري الحزم مدعومون؟ هل يجب علي استخدام PNPM؟

بالنسبة لمساحات عمل Monorepo ، من المحتمل أن يكون PNPM هو الخيار الأسرع والأكثر موثوقية. عند استخدامه ، يوصى بشدة أن يستخدمه الجميع في الفريق. لا ينبغي تنفيذ أي تثبيتات ولا ينبغي ارتكاب أي ملفات قفل أخرى.

كبديل ، يتم دعم الغزل أيضًا ويمكن استخدامه للتثبيت. تحذيرات عند استخدام الغزل:

• يتم دعم النسخة المستقرة فقط من Yarn (حاليًا V3) ، وليس كلاسيكية Yarn (V1).
• يجب ارتكاب ملفات yarn.lock بدلاً من ملفات .pnpm-lock.yaml .
• لا يزال يستخدم pnpm CLI في العديد من البرامج package.json . json ، لذلك يجب تعديلها يدويًا.

[!مهم]
نظرًا لأن NPM يفتقر إلى دعم بروتوكول استيراد workspace ، فهو غير متوافق مع الحبر! Athon.

كيفية حل "لا يمكن العثور على الوحدة النمطية".

في بعض الأحيان ، لا يلتقط Next.js التغييرات (أي إبداعات الملفات) في contracts/deployments/{contract}/ المجلدات بشكل صحيح. على سبيل المثال ، عندما قمت فقط بنشر عقدة محلية لأول مرة وتعيين الواجهة الأمامية .env.local للاتصال بشبكة development .

لإصلاح هذا ، يمكنك حذف ذاكرة التخزين المؤقت للبناء في frontend/.next . هذا هو الحل الوحيد وسوف يجبر Next.js على إعادة بناء المشروع والتقاط الملفات الجديدة.

[!ملحوظة]
لمنع هذا السلوك ، يحتوي ملف contracts/package.json على نص postinstall صغير ينشئ ملف development.ts فارغ.

كيف تتعامل مع التصميم؟

حاليًا يوفر التصميم عبر الخيارات التالية خارج المربع:

• Shadcn/UI - المكونات القابلة للاستخدام المصممة باستخدام Radix UI و CSS Tailwind.
• أنماط الفانيليا Tailwind CSS عبر className و *.module.(s)css .
• الافتراضي (s) أنماط CSS.

[!معلومات]
يحاول Booilerplate أن يظل غير موثوق به فيما يتعلق بالتصميم ، مما يعني أنه يمكنك استخدام أي مكتبة للتصميم أو المكونات.

كيف تعمل تفاعلات العقد الآمنة من النوع؟

باستخدام typechain-polkadot ، يتم إنشاء أنواع لكل عقد (ملفات TypeScript) عند الإنشاء (عبر برنامج build Script أو build-all.sh ). يمكنك قمع هذا السلوك عن طريق التمرير- --skip-types .

يتم تخزينها بموجب contracts/typed-contracts/ وتم استيرادها مباشرة من الواجهة الأمامية. بعد ذلك ، من خلال خطاف useRegisteredTypedContract الجديد من مثيلات useInkathon مع API المحددة مسبقًا ، يتم إنشاء عنوان عقد معتمد الشبكة ، والموضوع المحقن. انظر greeter-contract-interactions.tsx .

الموارد لمعرفة المزيد عن الركيزة والحبر! و polkadot.js

• حبر! الوثائق
• وثائق polkadot.js
• بولكادوت ويكي حبر! أدوات
• الوثائق Aleph Zero
• الحبر! تسجيل ورشة Athon
• حبر! Athon Telegram Group