@agntn/puzzles

🧩 333 لغزاً ومكافأة عامة في مجال العملات المشفرة موزعة على إحدى عشرة مجموعة، كسجلات مُنمّطة. تطلب لغزاً، فتحصل على عنوانه، ومادته المفتاحية، وما حدث على السلسلة.

لماذا؟

كل خيط لغز يحتوي على الأشياء الثلاثة نفسها: العناوين، والجوائز، ومن حلّ ماذا. وكل ماسح ومتتبّع يعيد كتابتها من الخيط، بشكل مختلف قليلاً في كل مرة. لذا فهي تعيش هنا مرة واحدة، كشيفرة. اللغز هو سجل TypeScript. يقرأه مدقّق الأنواع قبل أن يقرأه أي اختبار. وCLI وخادم MCP وإضافتا Pi وOMP تقرأ سجلاً واحداً.

التوثيق، صفحة لكل لغز وملعب تفاعلي: puzzles.agntn.dev.

[!WARNING] إصدار ما قبل 1.0. لا تزال واجهة البرمجة، وأعلام CLI، ونموذج البيانات قابلة للتغيير. ثبّت إصداراً محدداً إذا كنت ستبني عليه.

✨ الميزات

• 🧾 البيانات كشيفرة. حرفي PuzzleSpec واحد لكل لغز، يُبنى بواسطة مصنع خاص بسلسلته. لا JSON، ولا خطوة بناء.
• 🕳️ الغياب يعني الغياب. اللغز الذي لا يحتوي على حَلّال أو جائزة لا يملك هذا المفتاح. لا شيء يُسلسَل كـ null.
• 🔑 المادة المفتاحية بكل أشكالها. Hex، أو WIF، أو حمولة BIP38، أو عبارة استرداد، أو حصص سرية، أو مجرد عرض بتّي. باني واحد.
• 💤 سجل كسول. استيراد الحزمة لا يحمّل أي سجلات. get("b1000/71") يستورد وحدة مجموعة واحدة.
• ✅ التحقق قيمة. مفتاح منشور يشتقّ العنوان أو لا يشتقّه. لا شيء يُطلق استثناءً بسبب سجل سيئ.
• 💰 أرصدة حيّة. puzzle.balance() عبر @agntn/explorers. الوحدات الأساسية كـ bigint، ومفاتيح API محجوبة من الأخطاء.
• 🤖 ست أدوات للوكلاء. منفّذ واحد خلف MCP وPi وOMP. الإجابة نفسها في كل مكان.
• 🌐 يعمل في أي مكان. ESM محايد على Fetch API. Node، والمتصفحات، وعمّال الحافة.

📦 التثبيت

pnpm add @agntn/puzzles

Node.js 24 أو أحدث لـ CLI.

🚀 أول استدعاء

npx @agntn/puzzles stats

Total: 333
Solved: 131
Unsolved: 93
Claimed: 11
Swept: 96
Expired: 2
With pubkey: 237

لا مفتاح، ولا إعداد، ولا شبكة. تُشحن السجلات داخل الحزمة. الأمر puzzles المجرّد أدناه هو pnpm exec puzzles بعد pnpm add محلي، أو مجرد puzzles بعد pnpm add -g @agntn/puzzles.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

الأوامر

الأمر	ما يطبعه
puzzles stats	الإجماليات وعدد الحالات. --json يضيف مجاميع الجوائز
puzzles collections	صف واحد لكل مجموعة: المفتاح، والأعداد، والمؤلف
puzzles show <id>	لغز واحد. --json للسجل كاملاً
puzzles list [collection]	لغز واحد لكل سطر. --status و--with-pubkey يضيّقان النتائج
puzzles verify [id]	مفتاح منشور مقابل عنوانه. --all لكل لغز، مع رمز خروج 1 عند عدم التطابق
puzzles balance <id>	الرصيد الحيّ. --api-key أو ETHERSCAN_API_KEY لإيثيريوم
puzzles export	مجموعة البيانات كاملة مع data_version
puzzles mcp	خادم MCP عبر stdio

--json هو المُسلسِل نفسه في كل مكان، bigint كسلاسل نصية والحقول الغائبة محذوفة. الأعلام ورموز الخروج موجودة في دليل CLI.

🧠 المكتبة

import { get, stats, verifyPuzzle } from "@agntn/puzzles";
import { b1000 } from "@agntn/puzzles/collections/b1000";

const puzzle = await get("b1000/71"); // loads the b1000 collection, nothing else
puzzle?.address().value; // "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU"
puzzle?.keyRange(); // [2n ** 70n, 2n ** 71n - 1n]

verifyPuzzle(b1000.require(1)).verified; // true, key 1 derives its address
(await stats()).unsolved; // 93
(await b1000.require(71).balance()).totalUnits(); // 7.10190014 when I ran it, mempool.space decides

هذا معظم الأمر، حقاً. المجموعة هي مدخلها الخاص وكل ما عليها متزامن. أما العروض التي تمتد عبر المجموعات فتنتظر تحميلاً. الأخطاء تنحدر من PuzzlesError، وللأرصدة عائلتها الخاصة تحت BalanceError. والباقي في الأدلة: السجلات، السجل، عمليات البحث، التحقق، الأرصدة.

🗺️ المجموعات

المفتاح	الألغاز	السلاسل	ما هي
b1000	256	bitcoin	مفاتيح من 1 إلى 256 بت، عنوان واحد لكل منها
rushwallet	30	bitcoin	محافظ دماغية من مسابقة 2014
zden	15	bitcoin, ethereum, litecoin, decred	ألغاز Zden البصرية
arweave	12	arweave, ethereum	ألغاز النسيج لـ Tiamat
warp	6	bitcoin	تحديات المحفظة الدماغية scrypt من Keybase
hash_collision	6	bitcoin	مكافآت تصادم P2SH لـ Peter Todd
ballet	3	bitcoin	مفاتيح BIP38 مطبوعة على محافظ مادية
bitimage	2	bitcoin	عبارات استرداد مُجزّأة من الصور
bitaps	1	bitcoin	مخطط مشاركة سرية 3 من 5
gsmg	1	bitcoin	لغز صوري متعدد المراحل
movie_enigma	1	bitcoin	عناوين أفلام ككلمات استرداد، حُلّت 2026

المعرّفات هي collection/name. الثلاثة المفردة، gsmg وbitaps وmovie_enigma، هي المفتاح فقط. لكل مجموعة صفحة تحوي القصة، والغرائب، وكل لغز: puzzles.agntn.dev/collections.

🤖 الوكلاء

claude mcp add puzzles --scope user -- npx -y @agntn/puzzles mcp
pi install npm:@agntn/puzzles

{
  "mcpServers": {
    "puzzles": { "command": "npx", "args": ["-y", "@agntn/puzzles", "mcp"] }
  }
}

ست أدوات: puzzles_stats وpuzzles_collections وpuzzles_show وpuzzles_list وpuzzles_verify وpuzzles_balance. الأخيرة فقط تغادر العملية، وتعليقاتها تقول ذلك. ما يحمله النص وأين تكمن الحدود: دليل الوكلاء.

🚫 ما لا يفعله هذا

إنه لا يحلّ شيئاً. لا ماسح، ولا kangaroo، ولا كاسر محافظ دماغية، ولا تخمين حالة من قائمة معاملات. solved وswept وclaimed وexpired مكتوبة يدوياً، لأن معاملة مطالبة مع مفتاح منشور لا تزال تعني محلولاً. حقائق السلسلة تأتي من @agntn/chains، واشتقاق المفاتيح من @agntn/keys، والأرصدة من @agntn/explorers. هذه الحزمة لا تعيد تنفيذ أي منها.

🧩 إضافة لغز

ملف سجل واحد تحت src/collections/<key>/ وسطر واحد في وحدة المجموعة. ثم pnpm test يشغّل بوابة البيانات: معرّفات فريدة، وصيغ العناوين وtxid، واشتقاق المفاتيح، وحمولات BIP38، ومسارات الأصول، ولا قيم null. شكل السجل موجود في سجلات الألغاز والقواعد في CONTRIBUTING.md.

🛠️ التطوير