Skip to content

Commit 2ffa46e

Browse files
committed
Enhance ERC721 Ethscriptions Collection Parser and Manager
- Introduced new operations `create_collection_and_add_self` and `add_self_to_collection` for streamlined collection and item management. - Updated the `extract` method to support `ethscription_id` and improved import fallback handling. - Refactored item data structures to remove `ethscription_id` from item data during batch operations. - Enhanced validation and encoding processes for collection metadata and item attributes. - Added comprehensive tests for new functionalities, ensuring proper integration and behavior in the collections protocol.
1 parent 9e20f57 commit 2ffa46e

7 files changed

Lines changed: 522 additions & 257 deletions

‎app/models/erc721_ethscriptions_collection_parser.rb‎

Lines changed: 225 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,37 @@ class Erc721EthscriptionsCollectionParser
2525
'discord_link' => :string
2626
}
2727
},
28+
# New combined create op name used by the contract; keep legacy alias below
29+
'create_collection_and_add_self' => {
30+
keys: %w[metadata item],
31+
# ((CollectionParams),(ItemData)) with ethscription_id in ItemData
32+
abi_type: '((string,string,uint256,string,string,string,string,string,string,string,bytes32),(uint256,string,bytes32,string,string,(string,string)[],bytes32[]))',
33+
validators: {
34+
'metadata' => :collection_metadata,
35+
'item' => :single_item
36+
}
37+
},
38+
# Legacy alias retained for backwards compatibility
2839
'create_and_add_self' => {
2940
keys: %w[metadata item],
30-
# ((CollectionParams),(ItemData)) with ItemData including bytes32[] merkle_proof
3141
abi_type: '((string,string,uint256,string,string,string,string,string,string,string,bytes32),(uint256,string,bytes32,string,string,(string,string)[],bytes32[]))',
3242
validators: {
3343
'metadata' => :collection_metadata,
3444
'item' => :single_item
3545
}
3646
},
47+
# New single-item add op; keep legacy batch below for compatibility
48+
'add_self_to_collection' => {
49+
keys: %w[collection_id item],
50+
abi_type: '(bytes32,(uint256,string,bytes32,string,string,(string,string)[],bytes32[]))',
51+
validators: {
52+
'collection_id' => :bytes32,
53+
'item' => :single_item
54+
}
55+
},
3756
'add_items_batch' => {
3857
keys: %w[collection_id items],
39-
# Includes per-item merkle_proof (bytes32[]) as the final tuple element
58+
# Includes ethscription_id in each item
4059
abi_type: '(bytes32,(uint256,string,bytes32,string,string,(string,string)[],bytes32[])[])',
4160
validators: {
4261
'collection_id' => :bytes32,
@@ -95,7 +114,7 @@ class Erc721EthscriptionsCollectionParser
95114
}
96115
}.freeze
97116

98-
# Item keys for add_items_batch validation
117+
# Item keys for validation (includes ethscription_id; item must refer to itself)
99118
ITEM_KEYS_MIN = %w[item_index name ethscription_id background_color description attributes].freeze
100119
ITEM_KEYS_WITH_PROOF = %w[item_index name ethscription_id background_color description attributes merkle_proof].freeze
101120

@@ -104,11 +123,21 @@ class Erc721EthscriptionsCollectionParser
104123

105124
class ValidationError < StandardError; end
106125

107-
def self.extract(content_uri)
108-
new.extract(content_uri)
126+
DEFAULT_ITEMS_PATH = ENV['COLLECTIONS_ITEMS_PATH'] || 'items_by_ethscription.json'
127+
DEFAULT_COLLECTIONS_PATH = ENV['COLLECTIONS_META_PATH'] || 'collections_by_name.json'
128+
129+
def self.extract(content_uri, ethscription_id: nil, import_fallback: false, items_path: DEFAULT_ITEMS_PATH, collections_path: DEFAULT_COLLECTIONS_PATH, cutoff_number: nil)
130+
new.extract(content_uri, ethscription_id: ethscription_id, import_fallback: import_fallback, items_path: items_path, collections_path: collections_path, cutoff_number: cutoff_number)
109131
end
110132

111-
def extract(content_uri)
133+
def extract(content_uri, ethscription_id: nil, import_fallback: false, items_path: DEFAULT_ITEMS_PATH, collections_path: DEFAULT_COLLECTIONS_PATH, cutoff_number: nil)
134+
# Import-aware path takes precedence if enabled and id is provided
135+
if import_fallback && ethscription_id
136+
if (encoded = build_import_encoded_params(ethscription_id.to_s.downcase, items_path: items_path, collections_path: collections_path, cutoff_number: cutoff_number))
137+
return encoded
138+
end
139+
end
140+
112141
return DEFAULT_PARAMS unless valid_data_uri?(content_uri)
113142

114143
begin
@@ -154,6 +183,179 @@ def extract(content_uri)
154183

155184
private
156185

186+
# -------------------- Import fallback --------------------
187+
188+
# Returns [protocol, operation, encoded_data] or nil
189+
def build_import_encoded_params(id, items_path:, collections_path:, cutoff_number: nil)
190+
load_import_data(items_path: items_path, collections_path: collections_path)
191+
192+
item = @__items_by_id[id]
193+
return nil unless item
194+
195+
if cutoff_number && safe_uint(item['ethscription_number']) > cutoff_number
196+
return nil
197+
end
198+
199+
coll_name = item['collection_name']
200+
return nil unless coll_name
201+
202+
leader_id = @__leader_by_collection[coll_name]
203+
return nil unless leader_id
204+
205+
item_index = @__zero_index_by_id[id] || 0
206+
207+
if id == leader_id
208+
metadata = @__collections_by_name[coll_name]
209+
return nil unless metadata
210+
operation = 'create_collection_and_add_self'
211+
schema = OPERATION_SCHEMAS[operation]
212+
encoding_data = {
213+
'metadata' => build_metadata_object(metadata),
214+
'item' => build_item_object(item: item, item_id: id, item_index: item_index)
215+
}
216+
encoded_data = encode_operation(operation, encoding_data, schema)
217+
['erc-721-ethscriptions-collection'.b, operation.b, encoded_data.b]
218+
else
219+
operation = 'add_self_to_collection'
220+
schema = OPERATION_SCHEMAS[operation]
221+
encoding_data = {
222+
'collection_id' => to_bytes32_hex(leader_id),
223+
'item' => build_item_object(item: item, item_id: id, item_index: item_index)
224+
}
225+
encoded_data = encode_operation(operation, encoding_data, schema)
226+
['erc-721-ethscriptions-collection'.b, operation.b, encoded_data.b]
227+
end
228+
end
229+
230+
def load_import_data(items_path:, collections_path:)
231+
# Memoize parsed JSON and derived leader/index maps
232+
if @__loaded_items_path == items_path && @__loaded_collections_path == collections_path && @__items_by_id
233+
return
234+
end
235+
236+
items = JSON.parse(File.read(items_path))
237+
collections = JSON.parse(File.read(collections_path))
238+
239+
@__items_by_id = {}
240+
items.each { |k, v| @__items_by_id[k.to_s.downcase] = v }
241+
@__collections_by_name = collections
242+
243+
# Group items by collection and derive leader (min ethscription_number)
244+
groups = Hash.new { |h, k| h[k] = [] }
245+
@__items_by_id.each do |iid, it|
246+
cname = it['collection_name']
247+
next unless cname.is_a?(String) && !cname.empty?
248+
num = safe_uint(it['ethscription_number'])
249+
groups[cname] << [iid, num]
250+
end
251+
252+
@__leader_by_collection = {}
253+
groups.each do |cname, pairs|
254+
next if pairs.empty?
255+
@__leader_by_collection[cname] = pairs.min_by { |_id, num| num }[0]
256+
end
257+
258+
# Normalize item indices to zero-based
259+
@__zero_index_by_id = {}
260+
groups.each do |_cname, pairs|
261+
explicit = pairs.map { |(iid, _)| [iid, @__items_by_id[iid]['index']] }
262+
explicit_indices = explicit.filter_map { |_iid, idx| idx if idx.is_a?(Integer) }
263+
if explicit_indices.size == pairs.size
264+
min_idx = explicit_indices.min
265+
offset = (min_idx == 0) ? 0 : 1
266+
explicit.each { |iid, idx| @__zero_index_by_id[iid] = [idx - offset, 0].max }
267+
else
268+
pairs.sort_by { |_iid, num| num }.each_with_index { |(iid, _), i| @__zero_index_by_id[iid] = i }
269+
end
270+
end
271+
272+
@__loaded_items_path = items_path
273+
@__loaded_collections_path = collections_path
274+
end
275+
276+
# Build ordered JSON objects to match strict parser expectations
277+
def build_metadata_object(meta)
278+
name = safe_string(meta['name'])
279+
symbol = safe_string(meta['symbol'] || meta['slug'] || meta['name'])
280+
max_supply = safe_uint_string(meta['max_supply'] || meta['total_supply'] || 0)
281+
description = safe_string(meta['description'])
282+
logo_image_uri = safe_string(meta['logo_image_uri'])
283+
banner_image_uri = safe_string(meta['banner_image_uri'])
284+
background_color = safe_string(meta['background_color'])
285+
website_link = safe_string(meta['website_link'])
286+
twitter_link = safe_string(meta['twitter_link'])
287+
discord_link = safe_string(meta['discord_link'])
288+
289+
OrderedHash[
290+
'name', name,
291+
'symbol', symbol,
292+
'max_supply', max_supply,
293+
'description', description,
294+
'logo_image_uri', logo_image_uri,
295+
'banner_image_uri', banner_image_uri,
296+
'background_color', background_color,
297+
'website_link', website_link,
298+
'twitter_link', twitter_link,
299+
'discord_link', discord_link
300+
]
301+
end
302+
303+
def build_item_object(item:, item_id:, item_index:)
304+
attrs = Array(item['attributes']).map do |a|
305+
OrderedHash['trait_type', safe_string(a['trait_type']), 'value', safe_string(a['value'])]
306+
end
307+
308+
OrderedHash[
309+
'item_index', safe_uint_string(item_index),
310+
'name', safe_string(item['name']),
311+
'ethscription_id', to_bytes32_hex(item_id),
312+
'background_color', safe_string(item['background_color']),
313+
'description', safe_string(item['description']),
314+
'attributes', attrs
315+
]
316+
end
317+
318+
def to_bytes32_hex(val)
319+
h = safe_string(val).downcase
320+
raise ValidationError, "Invalid bytes32 hex: #{val}" unless h.match?(/\A0x[0-9a-f]{64}\z/)
321+
h
322+
end
323+
324+
# Integer coercion helper for import computations
325+
def safe_uint(val)
326+
case val
327+
when Integer then val
328+
when String then (val =~ /\A\d+\z/ ? val.to_i : 0)
329+
else 0
330+
end
331+
end
332+
333+
def safe_uint_string(val)
334+
n = case val
335+
when Integer then val
336+
when String then (val =~ /\A\d+\z/ ? val.to_i : 0)
337+
else 0
338+
end
339+
n = 0 if n.negative?
340+
n.to_s
341+
end
342+
343+
def safe_string(val)
344+
val.nil? ? '' : val.to_s
345+
end
346+
347+
def ordered_json(pairs)
348+
JSON.generate(OrderedHash[pairs.to_a.flatten])
349+
end
350+
351+
class OrderedHash < ::Hash
352+
def self.[](*args)
353+
h = new
354+
args.each_slice(2) { |k, v| h[k] = v }
355+
h
356+
end
357+
end
358+
157359
def valid_data_uri?(uri)
158360
DataUri.valid?(uri)
159361
end
@@ -166,10 +368,12 @@ def encode_operation(operation, data, schema)
166368
values = case operation
167369
when 'create_collection'
168370
build_create_collection_values(validated_data)
169-
when 'create_and_add_self'
371+
when 'create_collection_and_add_self', 'create_and_add_self'
170372
build_create_and_add_self_values(validated_data)
171373
when 'add_items_batch'
172374
build_add_items_batch_values(validated_data)
375+
when 'add_self_to_collection'
376+
build_add_self_to_collection_values(validated_data)
173377
when 'remove_items'
174378
build_remove_items_values(validated_data)
175379
when 'edit_collection'
@@ -401,6 +605,20 @@ def build_create_and_add_self_values(data)
401605
[metadata_tuple, item_tuple]
402606
end
403607

608+
def build_add_self_to_collection_values(data)
609+
item = data['item']
610+
item_tuple = [
611+
item[:itemIndex],
612+
item[:name],
613+
item[:ethscriptionId],
614+
item[:backgroundColor],
615+
item[:description],
616+
item[:attributes],
617+
item[:merkleProof]
618+
]
619+
[data['collection_id'], item_tuple]
620+
end
621+
404622
def build_add_items_batch_values(data)
405623
# Transform items to array format for encoding
406624
items_array = data['items'].map do |item|

‎app/models/protocol_extractor.rb‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ class ProtocolExtractor
55
COLLECTIONS_DEFAULT_PARAMS = Erc721EthscriptionsCollectionParser::DEFAULT_PARAMS
66
GENERIC_DEFAULT_PARAMS = GenericProtocolExtractor::DEFAULT_PARAMS
77

8-
def self.extract(content_uri)
8+
def self.extract(content_uri, ethscription_id: nil)
99
return nil unless content_uri.is_a?(String)
1010

1111
# Centralized validation: must be a valid data URI and JSON payload
@@ -28,7 +28,7 @@ def self.extract(content_uri)
2828

2929
# Try collections extractor next (if enabled)
3030
if ENV['ENABLE_COLLECTIONS'] == 'true'
31-
result = try_collections_extractor(content_uri)
31+
result = try_collections_extractor(content_uri, ethscription_id: ethscription_id)
3232
return result if result
3333
end
3434

@@ -63,9 +63,13 @@ def self.try_token_extractor(content_uri)
6363
end
6464
end
6565

66-
def self.try_collections_extractor(content_uri)
66+
def self.try_collections_extractor(content_uri, ethscription_id: nil)
6767
# Erc721EthscriptionsCollectionParser returns [''.b, ''.b, ''.b] if no match
68-
protocol, operation, encoded_data = Erc721EthscriptionsCollectionParser.extract(content_uri)
68+
protocol, operation, encoded_data = Erc721EthscriptionsCollectionParser.extract(
69+
content_uri,
70+
ethscription_id: ethscription_id,
71+
import_fallback: (ENV['ENABLE_COLLECTIONS_IMPORT'] == 'true')
72+
)
6973

7074
# Check if extraction succeeded
7175
if protocol != ''.b && operation != ''.b
@@ -129,8 +133,8 @@ def self.encode_token_params(params)
129133

130134
# Get protocol data formatted for L2 calldata
131135
# Returns [protocol, operation, encoded_data] for contract consumption
132-
def self.for_calldata(content_uri)
133-
result = extract(content_uri)
136+
def self.for_calldata(content_uri, ethscription_id: nil)
137+
result = extract(content_uri, ethscription_id: ethscription_id)
134138

135139
if result.nil?
136140
# No protocol detected - return empty protocol params

‎contracts/src/ERC721EthscriptionsCollection.sol‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,12 @@ contract ERC721EthscriptionsCollection is ERC721EthscriptionsEnumerableUpgradeab
6060

6161
function removeMember(bytes32 ethscriptionId, uint256 tokenId) external onlyFactory {
6262
require(_tokenExists(tokenId), "Token does not exist");
63-
63+
address owner = ownerOf(tokenId);
6464
// Mark token as non-existent (handles enumeration cleanup)
6565
_setTokenExists(tokenId, false);
6666

6767
// Emit burn-style transfer for indexers
68-
emit Transfer(ownerOf(tokenId), address(0), tokenId);
68+
emit Transfer(owner, address(0), tokenId);
6969

7070
emit MemberRemoved(ethscriptionId, tokenId);
7171
}
@@ -103,9 +103,9 @@ contract ERC721EthscriptionsCollection is ERC721EthscriptionsEnumerableUpgradeab
103103

104104
string memory mediaField = string.concat(
105105
',"',
106-
mediaType.escapeJSON(),
106+
mediaType,
107107
'":"',
108-
mediaUri,
108+
mediaUri.escapeJSON(),
109109
'"'
110110
);
111111

0 commit comments

Comments
 (0)