Tiện ích mở rộng Enumerable

Tiện ích mở rộng Enumerable là gì?

Enumerable Extension là phần tùy chọn của tiêu chuẩn token không thể thay thế ERC-721, cho phép hợp đồng thông minh và ứng dụng crypto tìm ID token NFT thông qua các truy vấn chỉ mục on-chain.

Tiện ích này thường được nhận diện bằng tên giao diện

hoặc tên triển khai .

Đặc tả ERC-721 chính thức định nghĩa tiện ích này là cách để hợp đồng công bố danh sách đầy đủ NFT hợp lệ và ID token do từng địa chỉ sở hữu.

Tiện ích bổ sung ba hàm:

, và .

Các hàm này bổ trợ cho giao diện chuyển và sở hữu cốt lõi của ERC-721.

Chúng không thay thế các hàm như

, , hoặc .

Enumerable Extension là tùy chọn, vì vậy hợp đồng NFT vẫn có thể tuân thủ đầy đủ ERC-721 mà không hỗ trợ tiện ích này.

Tại sao gọi là Enumerable?

Liệt kê một bộ sưu tập nghĩa là xác định từng thành phần bằng một chỉ mục hoặc phương thức có tổ chức khác.

Giao diện ERC-721 cốt lõi có thể cho ứng dụng biết ai sở hữu một ID token đã biết.

Giao diện này cũng có thể cho ứng dụng biết một địa chỉ sở hữu bao nhiêu NFT.

Tuy nhiên, giao diện cốt lõi không cung cấp hàm on-chain trực tiếp để tìm mọi ID token hiện có hoặc mọi ID token do một chủ sở hữu cụ thể nắm giữ.

Enumerable Extension khắc phục hạn chế này bằng cách bổ sung khả năng truy cập theo chỉ mục vào toàn bộ bộ sưu tập và tài sản của từng chủ sở hữu.

Ứng dụng có thể bắt đầu từ chỉ mục 0 rồi tiếp tục truy vấn các chỉ mục cao hơn cho đến khi đạt tổng nguồn cung hoặc số dư liên quan.

Interface ID của Enumerable Extension là gì?

Interface ID ERC-165 của ERC-721 Enumerable Extension là

.

Hợp đồng tương thích phải trả về

khi hàm được gọi với giá trị này.

Tiêu chuẩn phát hiện giao diện ERC-165 cho phép ứng dụng hỏi hợp đồng thông minh về những giao diện mà hợp đồng khai báo hỗ trợ.

Giao diện ERC-721 cốt lõi có Interface ID riêng, vì vậy ứng dụng có thể kiểm tra độc lập khả năng hỗ trợ giao diện cốt lõi và Enumerable.

Hợp đồng triển khai Enumerable Extension cũng phải triển khai giao diện ERC-721 cốt lõi.

Phản hồi phát hiện giao diện dương tính giúp kiểm tra khả năng tương thích nhưng không chứng minh rằng việc triển khai chính xác, bảo mật hoặc trung thực.

Các hàm được Enumerable Extension bổ sung

Enumerable Extension chỉ bổ sung ba hàm truy vấn công khai.

Hàm

trả về số NFT hợp lệ hiện được hợp đồng theo dõi.

Hàm

trả về ID token trong danh sách token toàn hợp đồng.

Hàm

trả về ID token trong số tài sản hiện do một chủ sở hữu nắm giữ.

Cả ba hàm đều là hàm view chỉ đọc theo giao diện tiêu chuẩn.

Tiện ích này không bổ sung hàm chuyển, phê duyệt, mint, burn, metadata hoặc royalty.

Hàm totalSupply

Hàm

trả về số NFT hợp lệ hiện có chủ sở hữu khác địa chỉ zero.

Hàm này báo cáo nguồn cung đang hoạt động, không phải nguồn cung tối đa có thể có.

Ví dụ, hợp đồng có thể báo tổng nguồn cung là 8,000 nhưng vẫn giữ quyền mint thêm NFT sau này.

Nếu NFT bị burn và không còn thuộc quyền sở hữu hợp lệ, tổng nguồn cung được báo cáo thường sẽ giảm.

Điều này có nghĩa

không nhất thiết bằng số NFT từng được mint.

Hàm này cũng không chứng minh bộ sưu tập có giới hạn nguồn cung vĩnh viễn.

Người dùng cần kiểm tra logic mint và các quyền đặc biệt để xác minh tuyên bố về độ khan hiếm.

Hàm tokenByIndex

Hàm

trả về ID token ở vị trí chỉ định trong danh sách toàn hợp đồng.

Chỉ mục bắt đầu từ 0.

Chỉ mục hợp lệ phải nhỏ hơn giá trị do

trả về.

Nếu tổng nguồn cung là 100, các chỉ mục hợp lệ là từ 0 đến 99.

Truy vấn chỉ mục 100 trở lên sẽ thất bại.

ID token trả về không bắt buộc phải bằng chỉ mục.

Ví dụ, chỉ mục 0 có thể trả ID token 500, còn chỉ mục 1 trả ID token 12.

Ứng dụng không bao giờ được mặc định rằng ID token là tuần tự chỉ vì các chỉ mục liệt kê là tuần tự.

Hàm tokenOfOwnerByIndex

Hàm

trả về một ID token do địa chỉ được chỉ định sở hữu.

Chỉ mục bắt đầu từ 0 và phải nhỏ hơn kết quả

của chủ sở hữu đó.

Nếu một địa chỉ sở hữu ba NFT, các chỉ mục hợp lệ của chủ sở hữu là 0, 1 và 2.

Hàm phải thất bại nếu chỉ mục nằm ngoài số dư hiện tại của chủ sở hữu.

Hàm cũng phải thất bại nếu địa chỉ chủ sở hữu được cung cấp là địa chỉ zero.

Hàm này cho phép ứng dụng on-chain và off-chain liệt kê NFT của một địa chỉ mà không cần tìm kiếm mọi ID token có thể có.

Cách ba hàm phối hợp với nhau

Ứng dụng có thể gọi

để biết hiện có bao nhiêu NFT hợp lệ.

Sau đó, ứng dụng có thể gọi

một lần cho mỗi chỉ mục từ 0 đến thấp hơn nguồn cung một đơn vị.

Với mỗi ID token trả về, ứng dụng có thể gọi

để xác định chủ sở hữu hiện tại.

Để liệt kê tài sản của một địa chỉ, ứng dụng có thể gọi

, rồi truy vấn cho từng chỉ mục hợp lệ của chủ sở hữu.

Quy trình này giúp tìm token thông qua các hàm on-chain tiêu chuẩn.

Bộ sưu tập lớn vẫn có thể cần nhiều lệnh gọi RPC, vì vậy ứng dụng thực tế thường dùng phân trang, xử lý theo lô, bộ nhớ đệm hoặc lập chỉ mục sự kiện.

Thứ tự liệt kê không được đảm bảo

Đặc tả ERC-721 không quy định thứ tự sắp xếp bắt buộc cho

hoặc .

Thứ tự trả về không nhất thiết dựa trên ID token, thời điểm mint, thời điểm chuyển, độ hiếm, metadata hoặc thời gian sở hữu.

Hợp đồng có thể thay đổi vị trí của một token khi token khác được chuyển hoặc burn.

Ứng dụng không được xem chỉ mục liệt kê là định danh cố định.

ID token là định danh ổn định trong hợp đồng, còn chỉ mục chỉ là vị trí tra cứu hiện tại.

Giao diện cần kết quả đã sắp xếp nên sắp xếp các ID token trả về off-chain theo quy tắc riêng.

Liệt kê bằng phương pháp swap-and-pop

Một cách triển khai phổ biến sử dụng kỹ thuật gọi là swap-and-pop để xóa ID token khỏi mảng một cách hiệu quả.

Khi token bị xóa, cách triển khai đưa token cuối cùng vào vị trí cũ của token bị xóa.

Sau đó, nó xóa phần tử cuối mảng.

Cách này tránh phải dịch chuyển mọi token phía sau và giữ độ phức tạp khi xóa tương đối thấp.

Tuy nhiên, nó làm thay đổi thứ tự các ID token còn lại.

Triển khai OpenZeppelin ERC721Enumerable hiện tại sử dụng phương pháp này cho cả chỉ mục toàn cục và chỉ mục theo chủ sở hữu.

Vì vậy, khi quyền sở hữu thay đổi trong quá trình liệt kê kéo dài, ứng dụng nên bắt đầu lại hoặc đối chiếu phân trang một cách cẩn thận.

Ví dụ liệt kê toàn bộ bộ sưu tập

Giả sử hợp đồng ERC-721 báo tổng nguồn cung là bốn.

Ứng dụng gọi

với các chỉ mục 0, 1, 2 và 3.

Hợp đồng trả về ID token 18, 42, 7 và 105.

Ứng dụng đã biết toàn bộ ID token hợp lệ dù các ID không tuần tự.

Ứng dụng có thể gọi

và cho từng ID để hiển thị quyền sở hữu và metadata.

Nếu ID token 42 bị burn sau đó, danh sách toàn cục có thể trả về 18, 105 và 7 vì cách triển khai có thể chuyển phần tử cuối vào vị trí vừa bị xóa.

Thay đổi này hợp lệ vì tiêu chuẩn không đảm bảo thứ tự liệt kê.

Ví dụ liệt kê theo chủ sở hữu

Giả sử Alice sở hữu ID token 9, 30 và 88 trong hợp đồng NFT hỗ trợ Enumerable.

Hàm

của hợp đồng trả về 3 cho địa chỉ của Alice.

Ứng dụng truy vấn các chỉ mục chủ sở hữu 0, 1 và 2 thông qua

.

Hợp đồng trả về ba ID token của Alice.

Sau đó Alice chuyển ID token 30 cho Bob.

Số dư của Alice giảm còn 2 và các ID token còn lại có thể xuất hiện theo thứ tự chỉ mục khác.

Ứng dụng nên đọc số dư đã cập nhật trước khi liệt kê lại token của chủ sở hữu.

Enumerable Extension và ERC-721 cốt lõi

Tiêu chuẩn ERC-721 cốt lõi cung cấp quyền sở hữu, chuyển token, phê duyệt, sự kiện và kiểm tra bên nhận an toàn.

Tiêu chuẩn có thể trả lời liệu một ID token đã biết có tồn tại và ai sở hữu nó hay không.

Tiêu chuẩn không cung cấp danh sách on-chain tiêu chuẩn gồm mọi ID token.

Enumerable Extension bổ sung lớp chức năng tìm kiếm đó.

Bộ sưu tập không hỗ trợ liệt kê vẫn có thể chuyển NFT bình thường và hoạt động với ví tương thích ERC-721.

Không hỗ trợ liệt kê không khiến NFT không hợp lệ hoặc không tuân thủ tiêu chuẩn.

Ứng dụng muốn tương thích ERC-721 rộng rãi phải hỗ trợ cả bộ sưu tập có và không có Enumerable.

Enumerable Extension và Metadata Extension

Enumerable Extension xác định ID token hiện có và tài sản của chủ sở hữu.

Metadata Extension cung cấp tên bộ sưu tập, ký hiệu và URI token.

Liệt kê không mô tả hình ảnh, thuộc tính, tiêu đề hoặc nội dung bên ngoài liên kết với NFT.

Hỗ trợ metadata không cung cấp danh sách token đầy đủ.

Hợp đồng có thể triển khai một, cả hai hoặc không triển khai tiện ích nào mà vẫn thực hiện chức năng ERC-721 cốt lõi.

Ứng dụng nên kiểm tra riêng từng giao diện.

Enumerable Extension và chỉ riêng totalSupply

Một số hợp đồng NFT bổ sung hàm

tùy chỉnh nhưng không triển khai đầy đủ Enumerable Extension.

Tên hàm quen thuộc không chứng minh rằng hợp đồng hỗ trợ

hoặc .

Ý nghĩa của hàm nguồn cung tùy chỉnh cũng có thể khác định nghĩa liệt kê ERC-721.

Hàm có thể báo số token từng được mint, ID token tiếp theo, kích thước tối đa của bộ sưu tập hoặc một giá trị khác theo dự án.

Ứng dụng nên dùng ERC-165 để kiểm tra toàn bộ giao diện Enumerable thay vì dựa vào một function selector.

Tại sao Enumerable Extension tốn nhiều gas hơn?

Việc liệt kê yêu cầu hợp đồng duy trì thêm các cấu trúc lưu trữ.

Cách triển khai phổ biến lưu một mảng gồm tất cả ID token hiện có.

Nó cũng lưu danh sách token theo chỉ mục của từng chủ sở hữu và các mapping ghi lại vị trí token.

Khi mint, hợp đồng phải thêm token mới vào cả danh sách toàn cục lẫn danh sách của chủ sở hữu.

Khi chuyển, hợp đồng phải xóa token khỏi danh sách của chủ sở hữu trước và thêm vào danh sách của chủ sở hữu mới.

Khi burn, hợp đồng phải xóa token khỏi cả danh sách chủ sở hữu lẫn danh sách toàn cục.

Các lần ghi dữ liệu bổ sung này làm tăng gas cho giao dịch thay đổi trạng thái.

Hướng dẫn triển khai ERC-721 hiện tại của OpenZeppelin lưu ý rằng tiện ích này thường bị lược bỏ vì tạo ra chi phí gas đáng kể.

Truy vấn liệt kê có miễn phí không?

Người dùng có thể gọi hàm view thông qua endpoint RPC mà không gửi giao dịch blockchain.

Trong trường hợp đó, không phải trả phí gas on-chain vì node mô phỏng lệnh đọc cục bộ.

Tuy nhiên, node vẫn phải xử lý và có thể áp dụng giới hạn tần suất hoặc hạn chế yêu cầu.

Nếu hợp đồng thông minh gọi hàm liệt kê trong giao dịch, việc xử lý sẽ tiêu tốn gas giao dịch.

Vòng lặp truy vấn hàng trăm hoặc hàng nghìn chỉ mục token on-chain có thể trở nên quá tốn kém để hoàn tất.

Nhà phát triển không nên nhầm lệnh đọc off-chain không tốn gas với khả năng tính toán on-chain không giới hạn.

Vòng lặp và giới hạn gas của block

Hợp đồng thông minh nên tránh các hàm thay đổi trạng thái có vòng lặp qua mọi NFT trong bộ sưu tập hoặc mọi NFT do một địa chỉ không bị giới hạn sở hữu.

Số vòng lặp có thể tăng theo thời gian cho đến khi giao dịch vượt giới hạn gas của block.

Tài liệu bảo mật Solidity cảnh báo rằng vòng lặp phụ thuộc vào dữ liệu lưu trữ cuối cùng có thể khiến thao tác hợp đồng không thể hoàn tất.

Hàm view được gọi off-chain không phát sinh cùng loại phí giao dịch, nhưng vẫn có thể làm quá tải nhà cung cấp RPC.

Ứng dụng nên dùng các trang có giới hạn, truy vấn từng chỉ mục hoặc lập chỉ mục off-chain cho tập dữ liệu lớn.

Lập chỉ mục sự kiện off-chain như một phương án thay thế

Mọi hợp đồng ERC-721 tuân thủ tiêu chuẩn đều phát sự kiện

khi NFT được mint, chuyển hoặc burn.

Indexer off-chain có thể xử lý các sự kiện này từ block triển khai hợp đồng để khôi phục quyền sở hữu hiện tại.

Mint thường được biểu diễn bằng giao dịch chuyển từ địa chỉ zero.

Burn thường được biểu diễn bằng giao dịch chuyển đến địa chỉ zero.

Giao dịch chuyển thông thường thay đổi quyền sở hữu giữa hai địa chỉ khác zero.

Lập chỉ mục sự kiện tránh các lần ghi lưu trữ bổ sung mà việc liệt kê on-chain yêu cầu.

Cách này cũng hỗ trợ tìm kiếm, sắp xếp, lọc và phân trang hiệu quả hơn với bộ sưu tập lớn.

Đổi lại, người dùng phải tin tưởng hoặc tự vận hành hệ thống lập chỉ mục và bảo đảm hệ thống luôn đồng bộ.

Enumerable Extension và lập chỉ mục sự kiện

Liệt kê on-chain cung cấp cho hợp đồng thông minh quyền truy cập tiêu chuẩn trực tiếp vào các chỉ mục token.

Lập chỉ mục sự kiện cung cấp khả năng tìm kiếm off-chain phong phú và dễ mở rộng hơn.

Liệt kê hữu ích khi hợp đồng khác phải xác minh hoặc chọn ID token mà không dựa vào cơ sở dữ liệu bên ngoài.

Lập chỉ mục sự kiện thường thiết thực hơn cho giao diện ví, trang bộ sưu tập, phân tích và tìm kiếm lịch sử.

Dự án có thể hỗ trợ cả hai phương thức.

Lựa chọn phù hợp phụ thuộc vào việc khả năng tìm kiếm on-chain có xứng đáng với lượng gas bổ sung phải trả cho mỗi lần mint, chuyển và burn hay không.

Liệt kê có hỗ trợ phân trang không?

Tiện ích này không định nghĩa hàm trả về một trang gồm nhiều ID token.

Tiện ích trả về một ID token cho mỗi truy vấn chỉ mục.

Ứng dụng off-chain có thể tạo phân trang bằng cách yêu cầu một phạm vi chỉ mục giới hạn.

Ví dụ, trang một có thể truy vấn chỉ mục 0 đến 49, còn trang hai truy vấn 50 đến 99.

Ứng dụng phải tính đến thay đổi về nguồn cung và thứ tự khi chuyển giữa các trang.

Giao dịch chuyển hoặc burn có thể làm token đổi chỉ mục, khiến quy trình phân trang kéo dài bỏ sót hoặc lặp lại ID.

Sử dụng dữ liệu tại một độ cao block cố định có thể tạo ảnh chụp nhất quán hơn nếu hệ thống RPC hỗ trợ truy vấn lịch sử.

Liệt kê có hiển thị mọi chủ sở hữu không?

Tiện ích này liệt kê ID token trên toàn bộ hợp đồng và ID token do một chủ sở hữu đã biết nắm giữ.

Tiện ích không cung cấp hàm trả về mọi địa chỉ chủ sở hữu duy nhất.

Ứng dụng có thể xác định chủ sở hữu bằng cách gọi

cho mọi ID token hoặc xử lý sự kiện chuyển.

Một chủ sở hữu có thể xuất hiện nhiều lần vì một địa chỉ có thể nắm giữ nhiều NFT.

Do đó, lập danh sách người nắm giữ duy nhất thường là công việc lập chỉ mục off-chain.

Liệt kê có chứng minh tính xác thực của token không?

Không. Liệt kê chỉ báo cáo ID token được một hợp đồng thông minh cụ thể theo dõi.

Bất kỳ ai cũng có thể triển khai hợp đồng ERC-721 có Enumerable với tên, hình ảnh, ký hiệu hoặc metadata sao chép.

Mạng blockchain và địa chỉ hợp đồng đầy đủ vẫn là những phần thiết yếu tạo nên danh tính NFT.

Giao diện Enumerable hoạt động chính xác không chứng minh bên phát hành sở hữu tác phẩm nghệ thuật, kiểm soát tài sản được tuyên bố hoặc có ý định trung thực.

Người dùng nên xác minh hợp đồng qua thông tin dự án có thẩm quyền và tự kiểm tra các quyền.

totalSupply có chứng minh độ khan hiếm không?

Số lượng nguồn cung hiện tại không xác lập mức tối đa vĩnh viễn.

Hợp đồng có thể có hàm mint công khai, quyền mint của quản trị viên, hệ thống mint qua bridge hoặc quyền nâng cấp.

ID token hiện không có chủ sở hữu cũng có thể được mint sau này.

Quy tắc nguồn cung của hợp đồng có thể thay đổi sau khi triển khai nếu hợp đồng có thể nâng cấp.

Người dùng nên xem xét mã và mô hình kiểm soát quyền trước khi dựa vào tuyên bố về độ khan hiếm.

Liệt kê giúp truy vấn nguồn cung hiện tại dễ dàng hơn nhưng không thực thi các cam kết kinh tế.

Mint và liệt kê

Khi một NFT mới được mint, cách triển khai Enumerable phải thêm ID token vào chỉ mục toàn cục và chỉ mục của chủ sở hữu đầu tiên.

Sau đó, tổng nguồn cung tăng thêm một.

ID token có thể xuất hiện ở bất kỳ chỉ mục toàn cục hợp lệ nào theo cách triển khai.

Chính sách mint tuần tự không bắt buộc chỉ mục liệt kê luôn bằng ID token.

Logic mint tùy chỉnh phải cập nhật nhất quán mọi cấu trúc liệt kê bắt buộc.

Cập nhật thiếu có thể khiến số dư, hồ sơ quyền sở hữu, tổng nguồn cung và kết quả liệt kê không khớp nhau.

Chuyển token và liệt kê

Giao dịch chuyển thường không làm thay đổi tổng nguồn cung.

Giao dịch xóa ID token khỏi danh sách của chủ sở hữu trước và thêm token vào danh sách của người nhận.

Danh sách token toàn cục thường vẫn chứa cùng ID token đó.

Vị trí chỉ mục theo chủ sở hữu có thể thay đổi trong quá trình xóa.

Chuyển token cho chính mình đòi hỏi triển khai cẩn thận vì người gửi và người nhận là cùng một địa chỉ.

Các cách triển khai đã được rà soát xử lý điều kiện này mà không xóa nhầm hoặc nhân đôi token.

Burn và liệt kê

Burn xóa token khỏi quyền sở hữu ERC-721 hợp lệ.

Cách triển khai Enumerable xóa ID token bị burn khỏi danh sách của chủ sở hữu và danh sách toàn cục.

Tổng nguồn cung giảm.

Không nên tiếp tục sử dụng các chỉ mục toàn cục và chỉ mục chủ sở hữu cũ của token.

Các token khác có thể được chuyển vào vị trí đó thông qua thao tác xóa swap-and-pop.

Ứng dụng cần lịch sử nên dùng sự kiện thay vì dữ liệu liệt kê hiện tại để ghi nhận NFT đã burn.

Khả năng tương thích với mint theo lô

Một số cách triển khai ERC-721 hỗ trợ mint hàng loạt liên tiếp hoặc nén trong quá trình dựng hợp đồng.

Các hệ thống này có thể tính quyền sở hữu mà không ghi nhận từng token qua logic cập nhật liệt kê thông thường.

Triển khai OpenZeppelin hiện tại cảnh báo tiện ích mint liên tiếp của họ xung đột với

và không nên kết hợp hai tiện ích này.

Triển khai Enumerable hiện tại của OpenZeppelin cũng từ chối đường dẫn cập nhật số dư theo lô không được hỗ trợ.

Nhà phát triển không nên kết hợp các tiện ích chỉ vì từng tiện ích hoạt động độc lập.

Cần rà soát cùng nhau cơ chế kế thừa, lưu trữ, sự kiện, số dư và hook cập nhật.

Liệt kê và hợp đồng có thể nâng cấp

Hợp đồng NFT có thể nâng cấp cho phép bổ sung hoặc thay đổi logic sau triển khai nếu hệ thống quản trị cho phép.

Việc thêm liệt kê sau khi nhiều NFT đã tồn tại đòi hỏi sự cẩn trọng đặc biệt.

Kho lưu trữ liệt kê mới có thể bắt đầu trống dù hợp đồng cốt lõi đã theo dõi hàng nghìn token.

Có thể cần quy trình di chuyển dữ liệu để điền chỉ mục toàn cục và chỉ mục theo chủ sở hữu.

Vòng lặp di chuyển on-chain lớn có thể vượt giới hạn gas.

Lỗi bố cục lưu trữ cũng có thể làm hỏng dữ liệu quyền sở hữu hoặc phê duyệt hiện có.

Quản trị viên nâng cấp nên sử dụng quy trình di chuyển đã kiểm thử, giao dịch có giới hạn và đánh giá bảo mật độc lập.

Liệt kê và logic balanceOf tùy chỉnh

Liệt kê theo chủ sở hữu phụ thuộc vào thông tin số dư ERC-721 chính xác.

Tiện ích tính

bằng phương thức tùy chỉnh hoặc nén có thể xung đột với chỉ mục chủ sở hữu được lưu trữ.

Hướng dẫn triển khai hiện tại cảnh báo cụ thể rằng các tiện ích dùng logic số dư tùy chỉnh có thể không tương thích với liệt kê.

Nhà phát triển phải xác nhận rằng mọi thao tác mint, chuyển và burn cập nhật số lượng quyền sở hữu và chỉ mục thông qua các đường dẫn mã tương thích.

Hợp đồng báo số dư chủ sở hữu là năm nhưng chỉ lưu bốn ID token có chỉ mục là hợp đồng không nhất quán nội bộ.

Rủi ro bảo mật đối với ứng dụng tích hợp

Ứng dụng nên xác minh khả năng hỗ trợ Enumerable trước khi gọi các hàm mở rộng.

Ứng dụng cần xử lý lỗi vượt phạm vi thay vì cho rằng chỉ mục đã quan sát trước đó vẫn hợp lệ.

Không nên dựa vào thứ tự liệt kê để tính độ hiếm, mức ưu tiên hoặc giá trị tài chính.

Ứng dụng nên ngăn kết quả trùng hoặc thiếu khi trạng thái thay đổi trong quá trình phân trang.

Ứng dụng cũng cần xác minh mọi ID token trả về thuộc đúng hợp đồng và mạng dự kiến.

Với các quyết định giá trị cao, ứng dụng có thể cần ảnh chụp trạng thái nhất quán tại một block và mức finality phù hợp.

RPC và tính nhất quán dữ liệu

Tùy mạng và cấu hình yêu cầu, endpoint RPC có thể trả dữ liệu liệt kê từ block gần nhất, an toàn, đã finalized hoặc trong quá khứ.

Hai lệnh gọi ở độ cao block khác nhau có thể tạo danh sách nguồn cung hoặc chủ sở hữu khác nhau.

NFT vừa được chuyển có thể xuất hiện dưới các chủ sở hữu khác nhau trên những nguồn dữ liệu chưa đồng bộ.

Khi cần tính nhất quán, ứng dụng nên ghi lại số block dùng cho thao tác liệt kê nhiều lệnh gọi.

Hệ thống quan trọng có thể đối chiếu nhiều node hoặc vận hành node đã được xác minh độc lập.

Liệt kê loại bỏ sự phụ thuộc vào API riêng của bộ sưu tập nhưng không loại bỏ mọi vấn đề về độ tin cậy RPC.

Lợi ích của Enumerable Extension

Tiện ích cung cấp cách tiêu chuẩn để tìm tất cả ID token hiện tại.

Tiện ích cho phép hợp đồng thông minh khác truy vấn NFT của chủ sở hữu mà không cần indexer bên ngoài.

Tiện ích cung cấp hàm nguồn cung hiện tại tiêu chuẩn.

Tiện ích có thể đơn giản hóa bộ sưu tập nhỏ, trò chơi on-chain, hệ thống thành viên và ứng dụng cần chọn token trực tiếp.

Tiện ích cũng giúp truy vấn kho NFT cơ bản ngay cả khi website hoặc cơ sở dữ liệu riêng của dự án biến mất.

Hạn chế của Enumerable Extension

Tiện ích làm tăng gas khi mint, chuyển và burn.

Tiện ích không đảm bảo thứ tự token ổn định.

Tiện ích không có sẵn chức năng phân trang, sắp xếp, lọc hoặc liệt kê người nắm giữ.

Tiện ích báo cáo token hiện tại chứ không cung cấp hồ sơ lịch sử đầy đủ.

Tiện ích có thể không tương thích với mint hàng loạt nén hoặc hệ thống số dư tùy chỉnh.

Vòng lặp on-chain lớn vẫn bị giới hạn bởi gas giao dịch.

Tiện ích cũng không đảm bảo metadata, royalty, giá, tính xác thực hoặc giới hạn nguồn cung.

Khi nào dự án nên dùng tính năng liệt kê?

Dự án có thể hưởng lợi từ tính năng liệt kê khi hợp đồng thông minh cần tìm ID token trực tiếp on-chain.

Tính năng này cũng có thể phù hợp với bộ sưu tập nhỏ nếu chi phí chuyển bổ sung ở mức chấp nhận được.

Trò chơi có thể dùng tính năng này khi logic hợp đồng cần chọn một NFT của người chơi theo chỉ mục.

Hợp đồng thành viên có thể dùng tính năng này khi quy trình on-chain cần kiểm tra token thành viên hiện tại của một người nắm giữ.

Dự án vẫn nên giới hạn vòng lặp và cân nhắc mapping đơn giản hơn hoặc chỉ mục riêng của ứng dụng có hiệu quả hơn hay không.

Khi nào dự án có thể không dùng tính năng liệt kê?

Bộ sưu tập NFT lớn có thể tránh liệt kê để giảm chi phí cho mỗi lần mint, chuyển và burn.

Dự án cũng có thể không dùng nếu mọi chức năng tìm kiếm và khám phá đã dựa vào indexer sự kiện off-chain.

Hệ thống mint hàng loạt nén có thể dùng mô hình quyền sở hữu không hoạt động hiệu quả với kho lưu trữ liệt kê tiêu chuẩn.

Dự án không cần liệt kê token on-chain có thể ít hưởng lợi từ việc trả phí cho chỉ mục on-chain vĩnh viễn.

Quyết định nên dựa trên yêu cầu thực tế của ứng dụng, không phải giả định rằng mọi tiện ích tùy chọn đều cần thiết.

Cách nhà phát triển nên triển khai tiện ích

Nhà phát triển nên bắt đầu với một cách triển khai ERC-721 Enumerable được duy trì và rà soát thường xuyên.

Cần bảo đảm

trả về .

Mọi đường dẫn mint, chuyển và burn phải cập nhật chính xác chỉ mục toàn cục và chỉ mục theo chủ sở hữu.

Cần kiểm tra các tiện ích tùy chỉnh để phát hiện xung đột với quyền sở hữu, số dư, mint hàng loạt, wrapping, tạm dừng và nâng cấp.

Kiểm thử nên bao gồm chỉ mục đầu và cuối, chỉ mục ngoài phạm vi, chuyển cho chính mình, burn, mint lại nếu được phép và thay đổi quyền sở hữu nhiều lần.

Kiểm thử bất biến nên xác minh

bằng số token có thể liệt kê toàn cục.

Kiểm thử cũng cần xác minh số token có thể liệt kê của mỗi chủ sở hữu bằng kết quả

.

Cách người dùng kiểm tra hỗ trợ Enumerable

Bước đầu tiên là xác minh địa chỉ hợp đồng NFT và mạng blockchain.

Bước thứ hai là gọi

với .

Bước thứ ba là xác nhận giao diện ERC-721 cốt lõi cũng được hỗ trợ.

Bước thứ tư là so sánh

với một mẫu nhỏ các chỉ mục hợp lệ.

Bước thứ năm là so sánh kết quả

của chủ sở hữu với ID token do liệt kê theo chủ sở hữu trả về.

Các bước này có thể phát hiện sự bất nhất rõ ràng nhưng không thay thế việc rà soát toàn bộ hợp đồng.

Các lỗi thường gặp với Enumerable Extension

Một lỗi phổ biến là cho rằng mọi hợp đồng ERC-721 đều hỗ trợ liệt kê.

Lỗi khác là xem chỉ mục liệt kê như ID token cố định.

Lỗi thứ ba là cho rằng ID token xuất hiện theo thứ tự số hoặc thứ tự mint.

Lỗi thứ tư là xem

như giới hạn nguồn cung vĩnh viễn.

Lỗi thứ năm là lặp qua bộ sưu tập không giới hạn trong giao dịch thay đổi trạng thái.

Lỗi thứ sáu là bỏ qua thay đổi thứ tự trong lúc phân trang.

Lỗi thứ bảy là cho rằng hàm

tùy chỉnh chứng minh hợp đồng hỗ trợ toàn bộ tiện ích.

Lỗi thứ tám là kết hợp các cách triển khai mint hàng loạt và liệt kê không tương thích.

Lỗi thứ chín là thêm liệt kê vào bộ sưu tập có thể nâng cấp mà không di chuyển các token đã tồn tại.

Lỗi thứ mười là xem hỗ trợ giao diện Enumerable như bằng chứng bộ sưu tập NFT xác thực hoặc có giá trị.

FAQ

Enumerable Extension trong crypto có nghĩa là gì?

Thông thường, thuật ngữ này chỉ tiện ích ERC-721 tùy chọn cho phép ứng dụng liệt kê mọi ID token NFT hiện tại và ID token do một địa chỉ cụ thể sở hữu.

Enumerable Extension có bắt buộc đối với ERC-721 không?

Không. Hợp đồng NFT có thể tuân thủ ERC-721 cốt lõi mà không hỗ trợ liệt kê.

Interface ID của Enumerable Extension là gì?

Interface ID ERC-165 là

.

Tiện ích này bổ sung những hàm nào?

Tiện ích bổ sung

, và .

totalSupply trả về gì?

Hàm trả về số NFT hiện hợp lệ mà hợp đồng đang theo dõi.

totalSupply có hiển thị nguồn cung tối đa có thể có không?

Không. Hàm báo nguồn cung hiện tại và không chứng minh rằng không thể mint thêm trong tương lai.

tokenByIndex trả về gì?

Hàm trả về ID token được lưu tại chỉ mục liệt kê toàn cục được chỉ định.

tokenOfOwnerByIndex trả về gì?

Hàm trả về một ID token thuộc sở hữu của địa chỉ được chỉ định tại chỉ mục chủ sở hữu được chỉ định.

Chỉ mục liệt kê có bắt đầu từ 0 không?

Có. Chỉ mục hợp lệ bắt đầu từ 0 và kết thúc ở vị trí thấp hơn một đơn vị so với nguồn cung hoặc số dư liên quan.

Chỉ mục liệt kê có giống ID token không?

Không. Chỉ mục là vị trí tạm thời trong danh sách, còn ID token nhận diện NFT trong hợp đồng.

ID token có được trả về theo thứ tự số không?

Không. Tiêu chuẩn không yêu cầu thứ tự liệt kê cụ thể.

Thứ tự liệt kê có thể thay đổi không?

Có. Giao dịch chuyển và burn có thể làm thay đổi vị trí chỉ mục, đặc biệt trong cách triển khai dùng phương pháp xóa swap-and-pop.

Burn NFT có làm giảm totalSupply không?

Có. Hợp đồng Enumerable được triển khai đúng sẽ xóa NFT đã burn và giảm tổng nguồn cung hiện tại.

Chuyển NFT có làm thay đổi totalSupply không?

Không. Giao dịch chuyển thông thường thay đổi danh sách theo chủ sở hữu nhưng không thay đổi số NFT hiện có.

Tại sao tiện ích này tốn kém?

Tiện ích cần ghi dữ liệu lưu trữ bổ sung để duy trì chỉ mục token toàn cục và theo chủ sở hữu trong các thao tác mint, chuyển và burn.

Lệnh gọi liệt kê có miễn phí không?

Lệnh đọc RPC off-chain không cần trả gas on-chain, nhưng lệnh gọi hợp đồng thông minh trong giao dịch vẫn tiêu tốn gas.

Hợp đồng có thể lặp qua mọi NFT hỗ trợ Enumerable không?

Hợp đồng có thể thử, nhưng vòng lặp on-chain không giới hạn cuối cùng có thể vượt giới hạn gas của block.

Tiện ích có hỗ trợ phân trang không?

Không. Ứng dụng tự tạo phân trang bằng cách truy vấn các phạm vi chỉ mục được chọn.

Tiện ích có liệt kê mọi người nắm giữ NFT không?

Không. Tiện ích liệt kê ID token trên toàn cục và của một chủ sở hữu đã biết nhưng không trả về danh sách duy nhất gồm mọi địa chỉ chủ sở hữu.

Lập chỉ mục sự kiện có thể thay thế liệt kê không?

Có. Indexer off-chain có thể khôi phục nguồn cung và quyền sở hữu token từ các sự kiện Transfer của ERC-721.

Liệt kê có bao gồm metadata NFT không?

Không. Metadata được cung cấp qua một tiện ích ERC-721 tùy chọn riêng.

Liệt kê có chứng minh NFT xác thực không?

Không. Bất kỳ ai cũng có thể triển khai hợp đồng Enumerable, vì vậy người dùng phải xác minh mạng, địa chỉ hợp đồng, bên phát hành và quyền hạn.

Có thể bổ sung liệt kê sau khi triển khai không?

Hợp đồng có thể nâng cấp có thể bổ sung tính năng này, nhưng phải di chuyển an toàn các token hiện có vào cấu trúc chỉ mục mới.

ERC721Enumerable có tương thích với mọi tiện ích ERC-721 không?

Không. Mint hàng loạt nén và cách triển khai số dư tùy chỉnh có thể xung đột với kho lưu trữ Enumerable tiêu chuẩn.

Enumerable Extension hữu ích nhất khi nào?

Tiện ích hữu ích nhất khi hợp đồng hoặc ứng dụng cần truy cập on-chain tiêu chuẩn vào danh sách token hiện tại hoặc ID token của chủ sở hữu.

Kết luận

Enumerable Extension là tính năng ERC-721 tùy chọn giúp tìm ID token NFT thông qua các truy vấn on-chain tiêu chuẩn.

Interface ID của tiện ích là

.

Tiện ích bổ sung

, và .

Các hàm này có thể liệt kê bộ sưu tập hiện tại và ID token do một địa chỉ đã biết sở hữu.

Chỉ mục liệt kê không phải định danh cố định và tiêu chuẩn không đảm bảo thứ tự của chúng.

Tiện ích cũng không cung cấp metadata, royalty, danh sách người nắm giữ, hồ sơ lịch sử hoặc bằng chứng về nguồn cung cố định.

Việc duy trì chỉ mục toàn cục và theo chủ sở hữu cần thêm thao tác ghi lưu trữ, làm tăng gas khi mint, chuyển và burn.

Ứng dụng lớn thường dùng sự kiện Transfer của ERC-721 và lập chỉ mục off-chain thay vì trả phí cho việc liệt kê on-chain đầy đủ.

Nhà phát triển triển khai tiện ích phải đồng bộ mọi cấu trúc quyền sở hữu, số dư và chỉ mục trên tất cả đường dẫn thay đổi trạng thái.

Người dùng nên tự xác minh khả năng hỗ trợ giao diện, danh tính hợp đồng, quyền mint, quyền nâng cấp và nguồn cung hiện tại.

Hiểu về Enumerable Extension giúp người dùng crypto phân biệt việc tìm NFT trực tiếp on-chain với metadata, lịch sử sở hữu, độ khan hiếm và dịch vụ lập chỉ mục off-chain.