Skip to main contentA-REX Core

الورقة البيضاء · 16

الملاحق

المصادر المرجعية: contracts/standard/ .sol (CC0) وstandard/AREX CORE.md. ويمكن إعادة توليد معرّفات الواجهات بالأمر npm run interface ids.

الملحق أ: مرجع الواجهات

المصادر المرجعية: contracts/standard/*.sol (CC0) وstandard/AREX-CORE.md. ويمكن إعادة توليد معرّفات الواجهات بالأمر npm run interface-ids.

أ.1 ملخص المطابقة

الواجهةمعرّف ERC-165الرمزالخطاف
IERC11550xd9b67a26يجب—
IERC7943MultiToken0x41c4fbadيجب—
IARexBatch0xe22639e0يجب—
IARexHookManager0x964f4861يجب (getHooks)—
IARexAttest0xad603a6cينبغي (الرمز أو عقد مرافق)—
IARexHook0x332afcbb—يجب

أ.2 IARexBatch

struct BatchInit { bytes32 commodity; bytes32 unit; uint64 producedAt; uint64 expiresAt; bytes32 originRef; bytes32 metadataHash; string uri; }
struct Batch { address issuer; uint64 createdAt; uint8 status; bytes32 commodity; bytes32 unit; uint64 producedAt; uint64 expiresAt; bytes32 originRef; bytes32 metadataHash; string uri; }


event BatchCreated(uint256 indexed id, address indexed issuer, bytes32 indexed commodity, bytes32 unit, uint256 quantity, address to);
event BatchStatusChanged(uint256 indexed id, uint8 previousStatus, uint8 newStatus, bytes32 reason);
event BatchMetadataUpdated(uint256 indexed id, bytes32 metadataHash, string uri);
event BatchTransformed(address indexed operator, uint256[] inputIds, uint256[] inputAmounts, uint256[] outputIds, uint256[] outputAmounts, bytes32 processRef);


error ARexBatchNotFound(uint256 id);
error ARexBatchRetired(uint256 id);
error ARexInvalidBatch(bytes32 reason);
error ARexInvalidStatusTransition(uint256 id, uint8 from, uint8 to);
error ARexLengthMismatch();


function createBatch(BatchInit calldata init, uint256 quantity, address to, bytes calldata data) external returns (uint256 id);
function batchOf(uint256 id) external view returns (Batch memory);
function batchExists(uint256 id) external view returns (bool);
function totalSupply(uint256 id) external view returns (uint256);
function setBatchStatus(uint256 id, uint8 status, bytes32 reason) external;
function setBatchMetadata(uint256 id, bytes32 metadataHash, string calldata uri) external;
function transform(address from, address to, uint256[] calldata inputIds, uint256[] calldata inputAmounts, BatchInit[] calldata outputs, uint256[] calldata outputAmounts, bytes32 processRef) external returns (uint256[] memory outputIds);
function parentsOf(uint256 id) external view returns (uint256[] memory);

أ.3 IERC7943MultiToken (ERC-7943، حرفيًا)

event ForcedTransfer(address indexed from, address indexed to, uint256 indexed tokenId, uint256 amount);
event Frozen(address indexed account, uint256 indexed tokenId, uint256 amount);
error ERC7943CannotSend(address account);
error ERC7943CannotReceive(address account);
error ERC7943CannotTransfer(address from, address to, uint256 tokenId, uint256 amount);
error ERC7943InsufficientUnfrozenBalance(address account, uint256 tokenId, uint256 amount, uint256 unfrozen);
function forcedTransfer(address from, address to, uint256 tokenId, uint256 amount) external returns (bool result);
function setFrozenTokens(address account, uint256 tokenId, uint256 amount) external returns (bool result);
function canSend(address account) external view returns (bool allowed);
function canReceive(address account) external view returns (bool allowed);
function getFrozenTokens(address account, uint256 tokenId) external view returns (uint256 amount);
function canTransfer(address from, address to, uint256 tokenId, uint256 amount) external view returns (bool allowed);

أ.4 IARexHook وIARexHookManager

interface IARexHook is IERC165 {
    error ARexHookRejected(address hook, bytes32 code);
    function hookFlags() external view returns (uint8);
    function check(uint8 op, address operator, address from, address to, uint256 id, uint256 amount, bytes calldata data) external view returns (bytes32 code);
    function onExecuted(uint8 op, address operator, address from, address to, uint256 id, uint256 amount, bytes calldata data) external;
    function canSend(address account) external view returns (bool);
    function canReceive(address account) external view returns (bool);
}
interface IARexHookManager {
    event HookRegistered(address indexed hook, uint8 flags, uint256 position);
    event HookRemoved(address indexed hook);
    error ARexHookAlreadyRegistered(address hook);
    error ARexHookNotRegistered(address hook);
    error ARexInvalidHook(address hook);
    function getHooks() external view returns (address[] memory);
    function hookFlagsOf(address hook) external view returns (uint8);
    function registerHook(address hook) external;
    function removeHook(address hook) external;
}

أ.5 IARexAttest

struct Attestation { address issuer; bytes32 ref; uint64 issuedAt; uint64 expiresAt; bool revoked; }
event Attested(uint256 indexed id, bytes32 indexed topic, address indexed issuer, bytes32 ref, uint64 expiresAt);
event AttestationRevoked(uint256 indexed id, bytes32 indexed topic, address indexed issuer, bytes32 reason);
event TrustedIssuerUpdated(bytes32 indexed topic, address indexed issuer, bool trusted);
error ARexUntrustedIssuer(bytes32 topic, address issuer);
error ARexAttestationNotFound(uint256 id, bytes32 topic);
function attest(uint256 id, bytes32 topic, bytes32 ref, uint64 expiresAt) external;
function revokeAttestation(uint256 id, bytes32 topic, bytes32 reason) external;
function getAttestation(uint256 id, bytes32 topic) external view returns (Attestation memory);
function isAttested(uint256 id, bytes32 topic) external view returns (bool);
function isTrustedIssuer(bytes32 topic, address issuer) external view returns (bool);

أ.6 الثوابت (ARexCodes)

المجموعةالقيم
العملياتOP_MINT = 1، OP_TRANSFER = 2، OP_BURN = 3، OP_FORCED_TRANSFER = 4، OP_TRANSFORM = 5
أعلام الخطافHOOK_CHECK = 1، HOOK_EXECUTED = 2، HOOK_ELIGIBILITY = 4
الحالةSTATUS_ACTIVE = 0، STATUS_RETIRED = 255
الأكواد (keccak256("AREX:…"))PAUSED، FROZEN، SENDER_INELIGIBLE، RECEIVER_INELIGIBLE، SANCTIONED، BATCH_NOT_FOUND، BATCH_RETIRED، BATCH_INACTIVE، BATCH_EXPIRED، BATCH_NOT_PRODUCED، LIMIT_EXCEEDED، DOCUMENT_MISSING، SEASON_CLOSED، IN_TRANSIT، ATTESTATION_MISSING
الدوال المساعدةcommodity(scheme, code)، unit(code)، topic(name)، code(namespace, name)

أ.7 أدوار التنفيذ المرجعي

ISSUER_ROLE وTRANSFORMER_ROLE وSTATUS_ROLE وENFORCER_ROLE وHOOK_ADMIN_ROLE وPAUSER_ROLE وUPGRADER_ROLE وDEFAULT_ADMIN_ROLE على ARexToken (كل منها keccak256("AREX_<NAME>"))؛ وATTEST_ADMIN_ROLE على ARexAttestations. دوال العرض الإضافية: isExpired(id) وtransferCheck(from, to, id, amount)؛ والدالة الإضافية: burn(from, id, amount)؛ وخانة ERC-7201 0x8ed599b6be05dec05297c009a1279a71df771ad996fe924d0b5a47326ff60900.

أ.8 الخطافات والامتدادات المرجعية

العقدالنوعالدوال الرئيسية
PerishabilityHookخطافsetCommodityDecay، setBatchDecay، valueBps، secondsRemaining، isExpired
SeasonalHookخطافaddWindow، clearWindows، windowsOf، isOpen
DeliveryHookخطافschedule، pickUp، markInTransit، recordReading، confirmDelivered، cancel، dispute، resolve، getDelivery، lockedUnits
TraceabilityHookخطافrecordEvent، eventCount، getEvents؛ وعلم المُنشئ persist
CommodityPriceOracleامتدادsubmit، finalizeRound، latestAnswer، getRound، currentRound، isStale، setParameters
CarbonImmobilizationWrapperامتدادrecordImmobilization، linkToBatch، retire، release، attestBacking، backingOf، linksOf
ParametricInsuranceامتدادfund، issue، claim، expire، getPolicy، freeCapacity

أ.9 مخطط البيانات الوصفية

standard/schema/batch-metadata.schema.json (JSON Schema 2020-12). الحقول المطلوبة: schemaVersion وcommodity{scheme, code} وunit وquantity. المجموعات الاختيارية البارزة: traceabilityLotCode وgs1{gtin, lgtin, sscc, glnProducer, digitalLink} وproduction وorigin{country, originRef, eudr{ddsReference}, geohashPrecision, geohash} وquality{gradeScheme, grade, measurements[]} وstatus.table وattestations[] وdocuments[]{type, hash, uri, registry, registryId} وepcis{bizStep, disposition, readPoint, bizLocation} وrestricted{uri, hash, accessPolicy} وattributes[]. ومثال في standard/examples/batch-metadata.example.json.

الملحق ب: المسرد

المصطلحالمعنى
الدفعةمعرّف رمز ERC-1155 له سجل Batch: دفعة من سلعة واحدة بوحدة قياس واحدة ولها منشأ ووقت إنتاج مشتركان.
إعادة تكوين الدفعةعملية transform تكون مخرجاتها من السلعة ووحدة القياس نفسيهما للمدخلات وتكون كمياتها محفوظة (التقسيم، والدمج). وهي متاحة للحاملين في التنفيذ المرجعي.
المعالجةعملية transform تغيّر السلعة أو وحدة القياس أو الكمية. وتتطلب TRANSFORMER_ROLE في التنفيذ المرجعي.
النسبالرسم البياني الذي تشكّله أحداث BatchTransformed والدالة parentsOf.
الخطافعقد ينفّذ IARexHook، ويُسجَّل على رمز، ويُقيَّم بالترتيب عند كل عملية.
كود الرفضقيمة bytes32 تُرجعها check في الخطاف؛ وتعني 0 أن العملية مسموحة؛ والعُرف keccak256("NAMESPACE:NAME").
الأهليةإذن على مستوى الحساب بالإرسال أو الاستلام، تجيب عنه الخطافات الموسومة بـ HOOK_ELIGIBILITY؛ ويُتاح عبر canSend/canReceive في ERC-7943.
الرصيد المجمّدكميات يحوزها حساب لكنه لا يستطيع تحريكها (setFrozenTokens)؛ ويجوز أن يتجاوز الرصيد.
التحويل القسريتحريك كميات بواسطة ENFORCER_ROLE دون موافقة الحامل (ERC-7943).
الإفادة(batch, topic) → (issuer, reference, validity) تسجّلها جهة إصدار موثوقة لذلك الموضوع.
الموضوعقيمة bytes32 تحدد موضوع إفادة؛ وهو مفتوح؛ ويقابل مواضيع ادعاءات ERC-735 ومعرّفات مخططات EAS.
مرجع المنشأoriginRef: تجزئة أو مرجع إلى أدلة المنشأ؛ وليس إحداثيات أبدًا.
التزام البيانات الوصفيةmetadataHash، وهو keccak256 للمستند القياسي خارج السلسلة الموجود في uri.
الحالةقيمة دورة الحياة من نوع uint8؛ و0 نشطة، و255 مسحوبة من التداول (نهائية)؛ و1..254 تحددها جهة الإصدار.
CTE / KDEحدث التتبع الحرج / عنصر البيانات الرئيسي (FSMA 204).
DDSبيان العناية الواجبة (EUDR).
EPCISGS1 Electronic Product Code Information Services، مفردات الأحداث للتتبع (الإصدار 2.0).
CPR / CPR-eCédula de Produto Rural، مستحقات المحاصيل في البرازيل؛ والصيغة الإلكترونية مسجّلة لدى كيانات مخوّلة.
EWRإيصال مستودع إلكتروني بموجب قانون المستودعات الأمريكي.
MLETRقانون UNCITRAL النموذجي بشأن السجلات الإلكترونية القابلة للتحويل.
ERC-7943 (uRWA)واجهة الأصول الشاملة من العالم الحقيقي (Universal Real World Asset): التجميد، والتحويل القسري، والأهلية؛ حالة Final في مايو 2026.
ERC-3643 (T-REX)معيار رموز مقيّد بتصاريح للأوراق المالية على ERC-20؛ حالة Final في ديسمبر 2023.
ERC-7201تخطيط تخزين بفضاءات أسماء للعقود القابلة للترقية.

الملحق ج: المراجع

المعايير والمواصفات

  • Radomski, W. وآخرون. "EIP-1155: Multi Token Standard." Ethereum Improvement Proposals، 2018.
  • Vogelsteller, F., Buterin, V. "EIP-20: Token Standard." 2015.
  • "ERC-165: Standard Interface Detection." 2018.
  • "ERC-3643: T-REX — Token for Regulated EXchanges." Final، 15 ديسمبر 2023. https://eips.ethereum.org/EIPS/eip-3643
  • "ERC-7943: uRWA — Universal Real World Asset Interface." Final، 27 مايو 2026. https://eips.ethereum.org/EIPS/eip-7943
  • "ERC-7201: Namespaced Storage Layout." 2023.
  • "ERC-735: Claim Holder." 2017 (مسودة).
  • توثيق Ethereum Attestation Service.
  • GS1. "EPCIS and CBV Standard 2.0." 2022. GS1 US. "EPCIS Recommendations for FSMA 204 Critical Tracking Events." 2024.
  • UN/CEFACT. "Recommendation No. 20: Codes for Units of Measure Used in International Trade."
  • IETF RFC 8785. "JSON Canonicalization Scheme (JCS)." 2020.
  • توثيق OpenZeppelin Contracts 5.x؛ وإعلان الشراكة بين OpenZeppelin وT-REX Network، يوليو 2026.

اللوائح والقوانين

  • FDA. "Requirements for Additional Traceability Records for Certain Foods." القاعدة النهائية، Federal Register 87(219)، 2022؛ "Compliance Date Extension"، Federal Register، 7 أغسطس 2025.
  • اللائحة (الاتحاد الأوروبي) 2023/1115 (إزالة الغابات)؛ واللائحة (الاتحاد الأوروبي) 2025/2650 (التعديل)؛ والبيان الصحفي لمجلس الاتحاد الأوروبي، 18 ديسمبر 2025.
  • اللائحة (الاتحاد الأوروبي) 2023/1114 (MiCA)؛ وإرشادات ESMA بشأن تكييف الأصول المشفّرة بوصفها أدوات مالية، ديسمبر 2024.
  • European Data Protection Board. "Guidelines 02/2025 on processing of personal data through blockchain technologies"، الإصدار 2.0، 7 يوليو 2026.
  • SEC. Release No. 33-11412، 17 مارس 2026. SEC v. W.J. Howey Co.، 328 U.S. 293 (1946).
  • GENIUS Act، Public Law 119-27 (2025)؛ واللوائح التنفيذية، Federal Register، 18 أغسطس 2026.
  • Uniform Commercial Code، تعديلات 2022، المادة 12 (Controllable Electronic Records).
  • U.S. Warehouse Act؛ 7 CFR Part 869 (Electronic Warehouse Receipts).
  • UNCITRAL. "Model Law on Electronic Transferable Records." 2017. المملكة المتحدة، Electronic Trade Documents Act 2023.
  • Comisión Nacional de Valores (الأرجنتين). Resolución General 1150/2026. Ley 9.643 (سندات الوارانت).
  • البرازيل. Lei 8.929/1994، وLei 13.986/2020 (CPR)؛ وLei 11.076/2004 (CDA/WA)؛ وCVM Resolução 88 وConsulta Pública SDM 05/2025.
  • Verra. "Verra Addresses Crypto Instruments and Tokens." 2022؛ VCS Program Guide.
  • التوجيه (الاتحاد الأوروبي) 2024/825 (تمكين المستهلكين من أجل التحول الأخضر).

البحوث والصناعة

  • Zhang, P., Schmidt, D. C. "Blockchain Applications in Food Supply Chain Management: A Systematic Review." Journal of Food Engineering, 279, 2020.
  • Caro, M. P. et al. "Blockchain-based Traceability in Agri-Food Supply Chain Management." IEEE, 2018.
  • FAO. "The State of Food and Agriculture." 2023.
  • World Bank. "Future of Food: Harnessing Digital Technologies to Improve Food System Outcomes." 2022.
  • ERC3643 Association. "History of ERC-3643"؛ وإعلان مبادرة التقييس ISO TC 307.
  • Chainlink. "Automated Compliance Engine (ACE): Technical Overview." 2025–2026.

الملحق د: القوالب

د.1 الحد الأدنى من الخطاف

المصدر: contracts/examples/MyHook.sol (يستورد ../reference/hooks/ARexHookBase.sol و../standard/IARexBatch.sol).

contract MyHook is ARexHookBase {
    function hookFlags() public pure override returns (uint8) {
        return ARexCodes.HOOK_CHECK;
    }


    function check(uint8 op, address, address, address, uint256 id, uint256, bytes calldata)
        external
        view
        override
        returns (bytes32)
    {
        if (op != ARexCodes.OP_TRANSFER) return ARexCodes.OK;
        IARexBatch.Batch memory b = IARexBatch(msg.sender).batchOf(id);
        b; // decide from b.commodity, b.producedAt, b.expiresAt, b.status ...
        return ARexCodes.OK;
    }
}

د.2 النشر (إضافة الترقيات)

const token = await upgrades.deployProxy(await ethers.getContractFactory("ARexToken"), [admin, baseURI], { kind: "uups" });
const attestations = await (await ethers.getContractFactory("ARexAttestations")).deploy(admin, await token.getAddress());
await token.registerHook(await (await ethers.getContractFactory("EligibilityHook")).deploy(admin));
await token.registerHook(await (await ethers.getContractFactory("ExpiryHook")).deploy(true));

د.3 هيكل البيانات الوصفية

{ "schemaVersion": "1.0.0", "commodity": { "scheme": "HS", "code": "100199" }, "unit": "KGM", "quantity": 250000,
  "traceabilityLotCode": "…", "production": { "producedAt": "…" }, "origin": { "country": "AR", "originRef": "…" },
  "status": { "table": { "1": "IN_STORAGE" } }, "documents": [ { "type": "warehouse_receipt", "hash": "…", "registryId": "…" } ],
  "restricted": { "uri": "…", "hash": "…", "accessPolicy": "…" } }

الملحق هـ: الأسئلة الشائعة

هل A-REX هي ERC؟ ليس بعد. فالمواصفة مكتوبة بصيغة ERC وستُقدَّم بعد نشر إنتاجي وتنفيذات مستقلة وتدقيق. ولم يُسنَد أي رقم؛ ولا تستخدم الأسماء في الشيفرة البادئة ERC.

هل يجب أن أستخدم ARexToken؟ لا. نفّذ الواجهات بأي طريقة تشاء؛ والمرجع طريقة واحدة.

هل يجب أن أستخدم الخطافات المرجعية؟ لا. فهي عروض توضيحية. انسخها أو استبدلها أو اكتب خطافاتك الخاصة.

هل يستطيع خطاف منع تحويل قسري؟ يستطيع أن يُرجع كودًا للعملية OP_FORCED_TRANSFER، وسيتراجع الرمز. والخطافات المرجعية لا تفعل ذلك؛ أما خطاف يحكم الإنفاذ (كأن يشترط مرجع أمر) فقد يفعله.

أين تذهب الإحداثيات؟ في تخزين مقيَّد خارج السلسلة يُشار إليه من البيانات الوصفية، وليس على السلسلة أبدًا.

كيف أمثّل محصولًا مستقبليًا؟ producedAt = 0؛ وقيّد التحويلات بـ ExpiryHook(allowPreHarvestTransfers).

هل تُحفظ الكمية في transform؟ ليس بحكم المعيار؛ فالمرجع يتيح لأي حامل إعادة تكوين الدفعة حين تكون الكمية محفوظة، ويشترط TRANSFORMER_ROLE فيما عدا ذلك.

هل الرمز ورقة مالية؟ المعيار لا يحسم ذلك. العرض هو الذي يحسمه. اسأل مستشارًا قانونيًا؛ فسطح الإنفاذ موجود أيًا كانت الإجابة.