جولة تفصيلية في عقد ⁦ERC-721⁩ بلغة ⁦Vyper⁩

# @dev يُصدر عند تغير ملكية أي رمز مميز غير قابل للاستبدال (NFT) بأي آلية. يُصدر هذا الحدث عندما يتم
#      إنشاء الرموز المميزة غير القابلة للاستبدال (`from` == 0) وتدميرها (`to` == 0). استثناء: أثناء إنشاء العقد، يمكن
#      إنشاء وتعيين أي عدد من الرموز المميزة غير القابلة للاستبدال دون إصدار تحويل (Transfer). في وقت أي
#      تحويل، يتم إعادة تعيين العنوان المعتمد لذلك الرمز المميز غير القابل للاستبدال (إن وجد) إلى لا شيء.
# @param _from مرسل الرمز المميز غير القابل للاستبدال (إذا كان العنوان هو العنوان الصفري فهذا يشير إلى إنشاء رمز مميز).
# @param _to مستقبل الرمز المميز غير القابل للاستبدال (إذا كان العنوان هو العنوان الصفري فهذا يشير إلى تدمير الرمز المميز).
# @param _tokenId الرمز المميز غير القابل للاستبدال الذي تم تحويله.
event Transfer:
    sender: indexed(address)
    receiver: indexed(address)
    tokenId: indexed(uint256)

# @dev يُصدر هذا عندما يتم تغيير العنوان المعتمد لرمز مميز غير قابل للاستبدال أو إعادة تأكيده. يشير العنوان الصفري
#      إلى عدم وجود عنوان معتمد. عندما يُصدر حدث تحويل (Transfer)، يشير هذا أيضًا
#      إلى أن العنوان المعتمد لذلك الرمز المميز غير القابل للاستبدال (إن وجد) يتم إعادة تعيينه إلى لا شيء.
# @param _owner مالك الرمز المميز غير القابل للاستبدال.
# @param _approved العنوان الذي نقوم باعتماده.
# @param _tokenId الرمز المميز غير القابل للاستبدال الذي نقوم باعتماده.
event Approval:
    owner: indexed(address)
    approved: indexed(address)
    tokenId: indexed(uint256)

# @dev يُصدر هذا عندما يتم تمكين أو تعطيل مشغل لمالك. يمكن للمشغل إدارة
#      جميع الرموز المميزة غير القابلة للاستبدال الخاصة بالمالك.
# @param _owner مالك الرمز المميز غير القابل للاستبدال.
# @param _operator العنوان الذي نقوم بتعيين حقوق المشغل له.
# @param _approved حالة حقوق المشغل (صحيح إذا تم منح حقوق المشغل وخاطئ إذا
# تم إلغاؤها).
event ApprovalForAll:
    owner: indexed(address)
    operator: indexed(address)
    approved: bool

@view
@external
def balanceOf(_owner: address) -> uint256:
    """
    @dev يُرجع عدد الرموز المميزة غير القابلة للاستبدال المملوكة لـ `_owner`.
         يتراجع إذا كان `_owner` هو العنوان الصفري. تعتبر الرموز المميزة غير القابلة للاستبدال المعينة إلى العنوان الصفري غير صالحة.
    @param _owner العنوان المراد الاستعلام عن رصيده.
    """
    assert _owner != ZERO_ADDRESS

    return self.ownerToNFTokenCount[_owner]

@view
@external
def ownerOf(_tokenId: uint256) -> address:
    """
    @dev يُرجع عنوان مالك الرمز المميز غير القابل للاستبدال.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
    @param _tokenId معرف الرمز المميز غير القابل للاستبدال.
    """
    owner: address = self.idToOwner[_tokenId]
    # يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا
    assert owner != ZERO_ADDRESS
    return owner

@view
@external
def getApproved(_tokenId: uint256) -> address:
    """
    @dev الحصول على العنوان المعتمد لرمز مميز غير قابل للاستبدال واحد.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
    @param _tokenId معرف الرمز المميز غير القابل للاستبدال المراد الاستعلام عن اعتماده.
    """
    # يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا
    assert self.idToOwner[_tokenId] != ZERO_ADDRESS
    return self.idToApprovals[_tokenId]

@view
@external
def isApprovedForAll(_owner: address, _operator: address) -> bool:
    """
    @dev يتحقق مما إذا كان `_operator` مشغلًا معتمدًا لـ `_owner`.
    @param _owner العنوان الذي يملك الرموز المميزة غير القابلة للاستبدال.
    @param _operator العنوان الذي يتصرف نيابة عن المالك.
    """
    return (self.ownerToOperators[_owner])[_operator]

def _isApprovedOrOwner(_spender: address, _tokenId: uint256) -> bool:
    """
    @dev يُرجع ما إذا كان المنفق المحدد يمكنه تحويل معرف رمز مميز محدد
    @param spender عنوان المنفق المراد الاستعلام عنه
    @param tokenId uint256 معرف الرمز المميز المراد تحويله
    @return bool ما إذا كان msg.sender معتمدًا لمعرف الرمز المميز المحدد،
        أو مشغلًا للمالك، أو مالك الرمز المميز
    """
    owner: address = self.idToOwner[_tokenId]
    spenderIsOwner: bool = owner == _spender
    spenderIsApproved: bool = _spender == self.idToApprovals[_tokenId]
    spenderIsApprovedForAll: bool = (self.ownerToOperators[owner])[_spender]
    return (spenderIsOwner or spenderIsApproved) or spenderIsApprovedForAll

@internal
def _addTokenTo(_to: address, _tokenId: uint256):
    """
    @dev إضافة رمز مميز غير قابل للاستبدال إلى عنوان محدد
         يتراجع إذا كان `_tokenId` مملوكًا لشخص ما.
    """
    # يتراجع إذا كان `_tokenId` مملوكًا لشخص ما
    assert self.idToOwner[_tokenId] == ZERO_ADDRESS
    # تغيير المالك
    self.idToOwner[_tokenId] = _to
    # تغيير تتبع العدد
    self.ownerToNFTokenCount[_to] += 1


@internal
def _removeTokenFrom(_from: address, _tokenId: uint256):
    """
    @dev إزالة رمز مميز غير قابل للاستبدال من عنوان محدد
         يتراجع إذا لم يكن `_from` هو المالك الحالي.
    """
    # يتراجع إذا لم يكن `_from` هو المالك الحالي
    assert self.idToOwner[_tokenId] == _from
    # تغيير المالك
    self.idToOwner[_tokenId] = ZERO_ADDRESS
    # تغيير تتبع العدد
    self.ownerToNFTokenCount[_from] -= 1

@internal
def _clearApproval(_owner: address, _tokenId: uint256):
    """
    @dev مسح اعتماد عنوان محدد
         يتراجع إذا لم يكن `_owner` هو المالك الحالي.
    """
    # يتراجع إذا لم يكن `_owner` هو المالك الحالي
    assert self.idToOwner[_tokenId] == _owner
    if self.idToApprovals[_tokenId] != ZERO_ADDRESS:
        # إعادة تعيين الاعتمادات
        self.idToApprovals[_tokenId] = ZERO_ADDRESS

@internal
def _transferFrom(_from: address, _to: address, _tokenId: uint256, _sender: address):
    """
    @dev تنفيذ تحويل رمز مميز غير قابل للاستبدال.
         يتراجع ما لم يكن `msg.sender` هو المالك الحالي، أو مشغلًا مصرحًا له، أو العنوان
         المعتمد لهذا الرمز المميز غير القابل للاستبدال. (ملاحظة: `msg.sender` غير مسموح به في دالة خاصة لذا قم بتمرير `_sender`.)
         يتراجع إذا كان `_to` هو العنوان الصفري.
         يتراجع إذا لم يكن `_from` هو المالك الحالي.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
    """

    # التحقق من المتطلبات
    assert self._isApprovedOrOwner(_sender, _tokenId)
    # يتراجع إذا كان `_to` هو العنوان الصفري
    assert _to != ZERO_ADDRESS
    # مسح الاعتماد. يتراجع إذا لم يكن `_from` هو المالك الحالي
    self._clearApproval(_from, _tokenId)
    # إزالة الرمز المميز غير القابل للاستبدال. يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا
    self._removeTokenFrom(_from, _tokenId)
    # إضافة رمز مميز غير قابل للاستبدال
    self._addTokenTo(_to, _tokenId)
    # تسجيل التحويل
    log Transfer(_from, _to, _tokenId)

### دوال التحويل ###

@external
def transferFrom(_from: address, _to: address, _tokenId: uint256):
    """
    @dev يتراجع ما لم يكن `msg.sender` هو المالك الحالي، أو مشغلًا مصرحًا له، أو العنوان
         المعتمد لهذا الرمز المميز غير القابل للاستبدال.
         يتراجع إذا لم يكن `_from` هو المالك الحالي.
         يتراجع إذا كان `_to` هو العنوان الصفري.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
    @notice المتصل مسؤول عن تأكيد أن `_to` قادر على استقبال الرموز المميزة غير القابلة للاستبدال وإلا
            فقد تُفقد بشكل دائم.
    @param _from المالك الحالي للرمز المميز غير القابل للاستبدال.
    @param _to المالك الجديد.
    @param _tokenId الرمز المميز غير القابل للاستبدال المراد تحويله.
    """
    self._transferFrom(_from, _to, _tokenId, msg.sender)

@external
def safeTransferFrom(
        _from: address,
        _to: address,
        _tokenId: uint256,
        _data: Bytes[1024]=b""
    ):
    """
    @dev يحول ملكية رمز مميز غير قابل للاستبدال من عنوان إلى عنوان آخر.
         يتراجع ما لم يكن `msg.sender` هو المالك الحالي، أو مشغلًا مصرحًا له، أو
         العنوان المعتمد لهذا الرمز المميز غير القابل للاستبدال.
         يتراجع إذا لم يكن `_from` هو المالك الحالي.
         يتراجع إذا كان `_to` هو العنوان الصفري.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
         إذا كان `_to` عقدًا ذكيًا، فإنه يستدعي `onERC721Received` على `_to` ويتراجع إذا
         لم تكن القيمة المرجعة هي `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`.
         ملاحظة: يتم تمثيل bytes4 بواسطة bytes32 مع حشو
    @param _from المالك الحالي للرمز المميز غير القابل للاستبدال.
    @param _to المالك الجديد.
    @param _tokenId الرمز المميز غير القابل للاستبدال المراد تحويله.
    @param _data بيانات إضافية بدون تنسيق محدد، يتم إرسالها في الاستدعاء إلى `_to`.
    """
    self._transferFrom(_from, _to, _tokenId, msg.sender)

@external
def approve(_approved: address, _tokenId: uint256):
    """
    @dev تعيين أو إعادة تأكيد العنوان المعتمد لرمز مميز غير قابل للاستبدال. يشير العنوان الصفري إلى عدم وجود عنوان معتمد.
         يتراجع ما لم يكن `msg.sender` هو المالك الحالي للرمز المميز غير القابل للاستبدال، أو مشغلًا مصرحًا له للمالك الحالي.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا. (ملاحظة: هذا غير مكتوب في EIP)
         يتراجع إذا كان `_approved` هو المالك الحالي. (ملاحظة: هذا غير مكتوب في EIP)
    @param _approved العنوان المراد اعتماده لمعرف الرمز المميز غير القابل للاستبدال المحدد.
    @param _tokenId معرف الرمز المميز المراد اعتماده.
    """
    owner: address = self.idToOwner[_tokenId]
    # يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا
    assert owner != ZERO_ADDRESS
    # يتراجع إذا كان `_approved` هو المالك الحالي
    assert _approved != owner

    # تعيين الاعتماد
    self.idToApprovals[_tokenId] = _approved
    log Approval(owner, _approved, _tokenId)


@external
def setApprovalForAll(_operator: address, _approved: bool):
    """
    @dev يمكّن أو يعطل الاعتماد لطرف ثالث ("مشغل") لإدارة جميع
         أصول `msg.sender`. كما أنه يُصدر حدث ApprovalForAll.
         يتراجع إذا كان `_operator` هو `msg.sender`. (ملاحظة: هذا غير مكتوب في EIP)
    @notice يعمل هذا حتى إذا لم يكن المرسل يملك أي رموز مميزة في ذلك الوقت.
    @param _operator العنوان المراد إضافته إلى مجموعة المشغلين المصرح لهم.
    @param _approved صحيح إذا تم اعتماد المشغلين، وخاطئ لإلغاء الاعتماد.
    """
    # يتراجع إذا كان `_operator` هو `msg.sender`
    assert _operator != msg.sender
    self.ownerToOperators[msg.sender][_operator] = _approved
    log ApprovalForAll(msg.sender, _operator, _approved)

    """
    @dev دالة لسك الرموز المميزة
         يتراجع إذا لم يكن `msg.sender` هو الساك.
         يتراجع إذا كان `_to` هو العنوان الصفري.
         يتراجع إذا كان `_tokenId` مملوكًا لشخص ما.
    @param _to العنوان الذي سيتلقى الرموز المميزة المسكوكة.
    @param _tokenId معرف الرمز المميز المراد سكه.
    @return قيمة منطقية تشير إلى ما إذا كانت العملية ناجحة.
    """
    # يتراجع إذا لم يكن `msg.sender` هو الساك
    assert msg.sender == self.minter

@external
def burn(_tokenId: uint256):
    """
    @dev يحرق رمز ERC-721 مميز محدد.
         يتراجع ما لم يكن `msg.sender` هو المالك الحالي، أو مشغلًا مصرحًا له، أو العنوان
         المعتمد لهذا الرمز المميز غير القابل للاستبدال.
         يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا.
    @param _tokenId uint256 معرف رمز ERC-721 المميز المراد حرقه.
    """
    # التحقق من المتطلبات
    assert self._isApprovedOrOwner(msg.sender, _tokenId)
    owner: address = self.idToOwner[_tokenId]
    # يتراجع إذا لم يكن `_tokenId` رمزًا مميزًا غير قابل للاستبدال صالحًا
    assert owner != ZERO_ADDRESS
    self._clearApproval(owner, _tokenId)
    self._removeTokenFrom(owner, _tokenId)
    log Transfer(owner, ZERO_ADDRESS, _tokenId)