ArtQ

artq - query (ethereum) blockchain contracts / services for (meta) data about art collections via json-rpc

home :: github.com/pixelartexchange/artbase
bugs :: github.com/pixelartexchange/artbase/issues
gem :: rubygems.org/gems/artq
rdoc :: rubydoc.info/gems/artq

Usage

Step 0: Setup JSON RPC Client

The ArtQ command line tool gets the eth node uri via the INFURA_URI enviroment variable / key for now. Set the environment variable / key depending on your operating system (OS) e.g.:

set INFURA_URI=https://mainnet.infura.io/v3/<YOUR_KEY_HERE>

Query (Token) Collection Info

To use the artq command line tool pass in the art collection contract address in the hex (string) format.

Case No. 1 - "Off-Blockchain" Token Metadata

Let's try Moonbirds - an "off-blockchain" pixel art collection - with the token contract / service at 0x23581767a106ae21c074b2276d25e5c3e136a68b:

$ artq 0x23581767a106ae21c074b2276d25e5c3e136a68b           # or
$ artq 0x23581767a106ae21c074b2276d25e5c3e136a68b info

resulting in:

name: >Moonbirds<
symbol: >MOONBIRD<
totalSupply: >10000<

tokenURIs 0..2:
  tokenId 0:
    https://live---metadata-5covpqijaa-uc.a.run.app/metadata/0
  tokenId 1:
    https://live---metadata-5covpqijaa-uc.a.run.app/metadata/1
  tokenId 2:
    https://live---metadata-5covpqijaa-uc.a.run.app/metadata/2

Note: By default the tokenURI method gets called / queried for the first tokens (e.g. 0, 1, 2, etc.).

If you get a link back (e.g. starting with https:// or ipfs://) than the art collection is "off-blockchain" and you MUST follow / request the link to get the token metadata.

For example if you request https://live---metadata-5covpqijaa-uc.a.run.app/metadata/0 you get back:

{"name":"#0",
 "image":"https://live---metadata-5covpqijaa-uc.a.run.app/images/0",
 "external_url":"https://moonbirds.xyz/",
 "attributes":[
  {"trait_type":"Eyes","value":"Angry"},
  {"trait_type":"Outerwear","value":"Hoodie Down"},
  {"trait_type":"Body","value":"Tabby"},
  {"trait_type":"Feathers","value":"Gray"},
  {"trait_type":"Background","value":"Green"},
  {"trait_type":"Beak","value":"Small"}],
 "x_debug":["orig:9650"]}

Case No. 2 - "On-Blockchain" Token Metadata (With Inline Image)

Let's try The Saudis - an "on-blockchain" pixel art collection - with the token contract / service at 0xe21ebcd28d37a67757b9bc7b290f4c4928a430b1:

$ artq 0xe21ebcd28d37a67757b9bc7b290f4c4928a430b1       # or
$ artq 0xe21ebcd28d37a67757b9bc7b290f4c4928a430b1 info

resulting in:

name: >The Saudis<
symbol: >SAUD<
totalSupply: >5555<

tokenURIs 0..2:
  tokenId 0:

{"name":"The Saudis #0",
 "description":"Max Bidding",
 "image_data": "...",
 "external_url":"https://token.thesaudisnft.com/0",
 "attributes":
  [{"trait_type":"Head", "value":"Light 1"},
   {"trait_type":"Hair", "value":"Bald"},
   {"trait_type":"Facial Hair", "value":"Normal Brown Beard & Mustache"},
   {"trait_type":"Headwear", "value":"Haram Police Cap"},
   {"trait_type":"Eyewear", "value":"Regular Pixel Shades"},
   {"trait_type":"Mouthpiece", "value":"None"}]}

   tokenId 1:

{"name":"The Saudis #1",
 "description":"Max Bidding",
 "image_data":  "...",
 "external_url":"https://token.thesaudisnft.com/1",
 "attributes":
  [{"trait_type":"Head", "value":"Light 1"},
   {"trait_type":"Hair", "value":"Long Widow's Peak"},
   {"trait_type":"Facial Hair", "value":"Messy White Beard"},
   {"trait_type":"Headwear", "value":"Brown Shemagh & Agal"},
   {"trait_type":"Eyewear", "value":"Big Purple Shades"},
   {"trait_type":"Mouthpiece", "value":"None"}]}

  tokenId 2:

{"name":"The Saudis #2 🛢" ,
 "description":"Max Bidding",
 "image_data":  "...",
 "external_url":"https://token.thesaudisnft.com/2",
 "attributes":
  [{"trait_type":"Head", "value":"Dark 1"},
   {"trait_type":"Hair", "value":"Short Buzz Cut"},
   {"trait_type":"Facial Hair", "value":"Gradient Beard"},
   {"trait_type":"Headwear", "value":"Brown Shemagh & Agal"},
   {"trait_type":"Eyewear", "value":"Big Pixel Shades"},
   {"trait_type":"Mouthpiece", "value":"Shadowless Vape"}]}

Note: The artq command-line tool "auto-magically" decodes "on-blockchain" metadata in the base64 format and inline svg images in the base64 format get "cut" from the metadata and "pasted" decoded. Example for tokenId 0, that is, The Saudis #0:

<svg xmlns="http://www.w3.org/2000/svg"
      xmlns:xlink="http://www.w3.org/1999/xlink" image-rendering="pixelated"
      height="336" width="336">
  <foreignObject x="0" y="0" width="336" height="336">
    <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAJklEQVR42mNMbp32n4GGgHHUglELRi0YtWDUglELRi0YtWBoWAAAuD470bkESf4AAAAASUVORK5CYII="/>
  </foreignObject>
  <foreignObject x="0" y="0" width="336" height="336">
     <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAtklEQVRIiWNgGAXDHjASoeY/JfoJKfh/e2MDTklV/waCZjARYziPlCZWBVB5fD7EawHc8C/PrhNSRr4FlBhOlAWUAhZiFK3fdYqBgYGBIdDNDEOMEMDlA5TUUzZ1G4OHkRiKAmxi2ABRPsCWVPElX2SAMw6gaZxigMsCnJlH1b+BJMuJCiJkQGzQwMDgSKYwgBw0xPqEJAtIDR4GBgqDiJjSlGgf4Eg5BOsDUlMRMRUUCqB5KgIAHCwuITa/cDMAAAAASUVORK5CYII=" />
  </foreignObject>
  <foreignObject x="0" y="0" width="336" height="336">
     <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAaklEQVRIiWNgGAWjYBSMglEwBAAjPklnSZb/DAwMjDzCAgwbr7whywImItT8//L2Az4H4AUsRDqEoEGUWsDgLMnC8JSJFc6X/vebKhYwMiC5nlhDkQExcYAvIeBNJMRaADMI3TCChg8PAADd6xC7QG7FfAAAAABJRU5ErkJggg==" />
  </foreignObject>
  <foreignObject x="0" y="0" width="336" height="336">
     <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAcElEQVRIie2SsQ3AIAwEnwzDCpTMyiguGQEvQ5okQoljTNL6KiSes3gAnAlhIdu/nNOCoxAx5WvNlcyet40+CmccA0XXZrbcaIXQyuMm5gFBqEGEKyGmvFwRMLzBrC6tIvU3nGKu1LWcxeU4juP8YQdbhhrmTahwzwAAAABJRU5ErkJggg==" />
  </foreignObject>
  <foreignObject x="0" y="0" width="336" height="336">
     <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAATElEQVRIie2PwQoAIAhDXf//z+tQgYnWoVOwdxHm2NRMCPE/qBYkDQBfs1rpDuEk10SmV5QFPmh+k3lSfTv0UDAM7hNfGvVbkRDiZzpfrCH/gTYLqwAAAABJRU5ErkJggg==" />
  </foreignObject>
  <foreignObject x="0" y="0" width="336" height="336">
     <img xmlns="http://www.w3.org/1999/xhtml" height="336" width="336" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAJklEQVRIie3NMQEAAAjDMMC/52ECvlRA00nqs3m9AwAAAAAAAJy1C7oDLddyCRYAAAAASUVORK5CYII=" />
     </foreignObject>
  </svg>

Case No. 3 - "On-Blockchain" Layers (Incl. Metadata & Images)

Note: Some "on-blockchain" pixel art collections include all layers, that is, metadata and images to compose / make-up "on-blockchain" token images "on-demand / on-the-fly" from "trait" building blocks from scratch.

If the contract uses / supports:

traitDetails(uint256 _layerIndex, uint256 _traitIndex) returns (string _name, string _mimetype, bool _hide) and
traitData(uint256 _layerIndex, uint256 _traitIndex) returns string

than you can "auto-magically" download all "on-blockchain" layers, that is, all metadata triplets by repeatedly calling traitDetails starting with index 0/0, 0/1, ..., 1/0, 1/1, ... and so on e.g.

traitDetails( 0, 0 ) => ["Rainbow Puke", "image/png", false]
traitDetails( 0, 1 ) => ["Bubble Gum", "image/png", false]
...
traitDetails( 1, 0 ) => ["Gold Chain", "image/png", false]
traitDetails( 2, 1 ) => ["Bowtie", "image/png", false]
...

and all images (as binary blobs) by calling traitData e.g.

traitData( 0, 0 ) => "\x89PNG..."
traitData( 0, 1 ) => "\x89PNG..."
...

and so on.

Let's try Mad Camels - an "on-blockchain" pixel art collection - with the token contract / service at 0xad8474ba5a7f6abc52708f171f57fefc5cdc8c1c:

$ artq 0xad8474ba5a7f6abc52708f171f57fefc5cdc8c1c layers

resulting in a temp(orary) directory holding all images:

/0_0.png
 0_1.png
 ...
 1_0.png
 1_1.png
 ...

and a datafile with all metadata in the comma-separated values (csv) format, that is, layers.csv e.g:

index, name, type, hide
0/0, Rainbow Puke, image/png, false
0/1, Bubble Gum, image/png, false
0/2, Vape, image/png, false
0/3, None, image/png, false
0/4, Cigarette, image/png, false
0/5, Pipe, image/png, false
1/0, Gold Chain, image/png, false
1/1, Bowtie, image/png, false
1/2, Gold Necklace, image/png, false
1/3, None, image/png, false
2/0, Eye Patch, image/png, false
2/1, Nerd Glasses, image/png, false
2/2, Blue Beams, image/png, false
2/3, Purple Eye Shadow, image/png, false
2/4, Gold Glasses, image/png, false
2/5, Holographic, image/png, false
2/6, Clown Eyes Red, image/png, false
2/7, Clown Eyes Green, image/png, false
2/8, Eye Mask, image/png, false
2/9, Laser Eye, image/png, false
2/10, VR, image/png, false
2/11, 3D Glasses, image/png, false
2/12, None, image/png, false
2/13, Yellow Glasses, image/png, false
2/14, Cool Glasses, image/png, false
2/15, Purple Glasses, image/png, false
2/16, Green Glasses, image/png, false
3/0, Diamond, image/png, false
3/1, Silver, image/png, false
3/2, Gold, image/png, false
3/3, None, image/png, false
4/0, Crown, image/png, false
4/1, Wireless Earphone, image/png, false
4/2, Flower, image/png, false
4/3, Fez, image/png, false
4/4, Fire, image/png, false
4/5, Beanie, image/png, false
4/6, Headphone, image/png, false
4/7, White Shemagh, image/png, false
4/8, Red And White Shemagh, image/png, false
4/9, Angle Ring, image/png, false
4/10, Blue Mohawk, image/png, false
4/11, Sombrero, image/png, false
4/12, Red Mohawk, image/png, false
4/13, Blue Bandana, image/png, false
4/14, Viking, image/png, false
4/15, Pilot Helmet, image/png, false
4/16, Top Hat, image/png, false
4/17, Captain Hat, image/png, false
4/18, Thief Hat, image/png, false
4/19, Orange Cap, image/png, false
4/20, Pirate Bandana, image/png, false
4/21, Knitted Cap, image/png, false
4/22, Purple Cap, image/png, false
4/23, Black Cap, image/png, false
4/24, Pirate Hat, image/png, false
4/25, None, image/png, false
4/26, Red Cap, image/png, false
4/27, Cop Hat, image/png, false
4/28, Cowboy Hat, image/png, false
4/29, Fedora, image/png, false
5/0, Mole, image/png, false
5/1, Pimple, image/png, false
5/2, None, image/png, false
6/0, Gold, image/png, false
6/1, Cyborg, image/png, false
6/2, Skeleton, image/png, false
6/3, Female, image/png, false
6/4, Robot, image/png, false
6/5, Zombie, image/png, false
6/6, Alien, image/png, false
6/7, Default, image/png, false
7/0, Desert, image/png, false
7/1, Cream, image/png, false
7/2, Pink, image/png, false
7/3, Purple, image/png, false
7/4, Green, image/png, false
7/5, Blue, image/png, false

Try some more art collections with "on-blockchain" layers such as Long Live Kevin, Aliens vs Punks, Chi Chis, Chopper, Inverse Punks, Marcs, Phunk Ape Origins, Punkin Spicies, and many more.

Tip: For more art collections with "on-blockchain" layers see the Art Factory Sandbox »

Using the ArtQ Machinery in Your Own Scripts

Yes, you can. Let's try the (crypto) marcs:

require 'artq'

marcs_eth  = "0xe9b91d537c3aa5a3fa87275fbd2e4feaaed69bd0"

marcs = ArtQ::Contract.new( marcs_eth )

n = 0
m = 0
res = marcs.traitData( n, m )    ## note: return binary blob (for n,m-index)
pp res
#=> ["\x89PNG..."]

res = marcs.traitDetails( n, m )  ## note: returns tuple (name, mimetype, hide?)
pp res
#=> ["Zombie", "image/png", false]



## or with convenience download_layers helper
ArtQ.download_layers( marcs_eth, outdir: './marcs' )

License

The scripts are dedicated to the public domain. Use it as you please with no restrictions whatsoever.

Questions? Comments?

Post them on the D.I.Y. Punk (Pixel) Art reddit. Thanks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

ArtQ

Usage

Step 0: Setup JSON RPC Client

Query (Token) Collection Info

Case No. 1 - "Off-Blockchain" Token Metadata

Case No. 2 - "On-Blockchain" Token Metadata (With Inline Image)

Case No. 3 - "On-Blockchain" Layers (Incl. Metadata & Images)

Using the ArtQ Machinery in Your Own Scripts

License

Questions? Comments?

Files

README.md

Latest commit

History

README.md

File metadata and controls

ArtQ

Usage

Step 0: Setup JSON RPC Client

Query (Token) Collection Info

Case No. 1 - "Off-Blockchain" Token Metadata

Case No. 2 - "On-Blockchain" Token Metadata (With Inline Image)

Case No. 3 - "On-Blockchain" Layers (Incl. Metadata & Images)

Using the ArtQ Machinery in Your Own Scripts

License

Questions? Comments?