Handle nullable OpenSea image URLs and fallback

Make OpenSea image fields optional and add original_image_url; implement fallback selection for resource and preview URLs in the mapper. Update mapping to use resource_url()/preview_url() helpers that prefer image_url, original_image_url, or display_image_url in a safe order, and replace direct field usage. Add a test asset JSON (asset_null_images.json) and a unit test to verify mapping when image/display URLs are null. Also adjust an existing test to use unwrap for brevity.

Author: gemcoder21

crates/nft/src/providers/opensea/mapper.rs

@@ -18,6 +18,9 @@ pub fn map_asset(response: NftResponse, asset_id: NFTAssetId) -> Option<NFTAsset
 impl Nft {
     pub fn as_primitive(&self, asset: NFTAssetId) -> Option<NFTAsset> {
         let traits = self.traits.clone().unwrap_or_default();
+        let resource_url = self.resource_url();
+        let preview_url = self.preview_url();
+
         Some(NFTAsset {
             id: asset.to_string(),
             collection_id: asset.get_collection_id().id(),
@@ -27,14 +30,30 @@ impl Nft {
             name: self.name.clone(),
             description: Some(self.description.clone()),
             chain: asset.chain,
-            resource: NFTResource::from_url(&self.image_url),
+            resource: NFTResource::from_url(resource_url),
             images: NFTImages {
-                preview: NFTResource::from_url(&self.display_image_url),
+                preview: NFTResource::from_url(preview_url),
             },
             attributes: traits.iter().flat_map(|x| x.as_attribute()).collect(),
         })
     }
 
+    fn resource_url(&self) -> &str {
+        self.image_url
+            .as_deref()
+            .or(self.original_image_url.as_deref())
+            .or(self.display_image_url.as_deref())
+            .unwrap_or_default()
+    }
+
+    fn preview_url(&self) -> &str {
+        self.display_image_url
+            .as_deref()
+            .or(self.image_url.as_deref())
+            .or(self.original_image_url.as_deref())
+            .unwrap_or_default()
+    }
+
     fn as_type(&self) -> Option<NFTType> {
         match self.token_standard.as_str() {
             "erc1155" => Some(NFTType::ERC1155),
@@ -180,7 +199,7 @@ mod tests {
 
         let asset_id = NFTAssetId::new(Chain::Ethereum, "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "1");
 
-        let nft_asset = response.nft.as_primitive(asset_id).expect("Failed to map asset");
+        let nft_asset = response.nft.as_primitive(asset_id).unwrap();
 
         assert_eq!(nft_asset.chain, Chain::Ethereum);
         assert_eq!(nft_asset.token_id, "1");
@@ -211,4 +230,25 @@ mod tests {
         assert!(nft_collection.links.iter().any(|link| link.url.contains("boredapeyachtclub.com")));
         assert!(nft_collection.links.iter().any(|link| link.url.contains("discord.gg")));
     }
+
+    #[test]
+    fn test_map_asset_with_null_image_urls() {
+        let response: NftResponse = serde_json::from_str(include_str!("../../../testdata/opensea/asset_null_images.json")).unwrap();
+        let asset_id = NFTAssetId::new(
+            Chain::Ethereum,
+            "0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401",
+            "66972740172774133895361774757009899712806299063970949277266423600598010529206",
+        );
+
+        let nft_asset = map_asset(response, asset_id).unwrap();
+
+        assert_eq!(nft_asset.chain, Chain::Ethereum);
+        assert_eq!(nft_asset.token_id, "66972740172774133895361774757009899712806299063970949277266423600598010529206");
+        assert_eq!(nft_asset.name, "gemdev.eth");
+        assert_eq!(
+            nft_asset.resource.url,
+            "https://metadata.ens.domains/mainnet/0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401/0x94113a45c5bedf735911bf707d70a6c05d9d99e76ece7e904c0eeda6591785b6/image"
+        );
+        assert_eq!(nft_asset.images.preview.url, nft_asset.resource.url);
+    }
 }

crates/nft/src/providers/opensea/model.rs

@@ -37,8 +37,9 @@ pub struct Nft {
     pub token_standard: TokenStandard,
     pub name: String,
     pub description: String,
-    pub image_url: String,
-    pub display_image_url: String,
+    pub image_url: Option<String>,
+    pub display_image_url: Option<String>,
+    pub original_image_url: Option<String>,
     pub traits: Option<Vec<Trait>>,
 }
 

crates/nft/testdata/opensea/asset_null_images.json

@@ -0,0 +1,56 @@
+{
+    "nft": {
+        "identifier": "66972740172774133895361774757009899712806299063970949277266423600598010529206",
+        "collection": "ens",
+        "contract": "0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401",
+        "token_standard": "erc1155",
+        "name": "gemdev.eth",
+        "description": "gemdev.eth, an ENS name.",
+        "image_url": null,
+        "display_image_url": null,
+        "display_animation_url": null,
+        "metadata_url": "https://metadata.ens.domains/mainnet/0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401/66972740172774133895361774757009899712806299063970949277266423600598010529206",
+        "opensea_url": "https://opensea.io/assets/ethereum/0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401/66972740172774133895361774757009899712806299063970949277266423600598010529206",
+        "updated_at": "2026-03-24T13:17:04.153143",
+        "is_disabled": false,
+        "is_nsfw": false,
+        "original_image_url": "https://metadata.ens.domains/mainnet/0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401/0x94113a45c5bedf735911bf707d70a6c05d9d99e76ece7e904c0eeda6591785b6/image",
+        "original_animation_url": null,
+        "traits": [
+            {
+                "trait_type": "Length",
+                "display_type": "NUMBER",
+                "max_value": null,
+                "value": "6"
+            },
+            {
+                "trait_type": "Created Date",
+                "display_type": null,
+                "max_value": null,
+                "value": "1774356395"
+            },
+            {
+                "trait_type": "Character Set",
+                "display_type": "STRING",
+                "max_value": null,
+                "value": "letter"
+            },
+            {
+                "trait_type": "Segment Length",
+                "display_type": "NUMBER",
+                "max_value": null,
+                "value": "6"
+            }
+        ],
+        "animation_url": null,
+        "is_suspicious": false,
+        "creator": "",
+        "owners": [
+            {
+                "address": "0x8d7460e51bcf4ed26877cb77e56f3ce7e9f5eb8f",
+                "quantity": 1
+            }
+        ],
+        "rarity": null
+    }
+}