ordinals 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 586a022b2167110472eaea7be6d88e4f21fe72ea1f05ed6465ce29913a10cc15
-  data.tar.gz: fe6f05e73dfdfd42560607c0721b0bdf642718debc83f48e0c36ba2a0ac82db2
+  metadata.gz: 4dbc3bf008b7d878df205f804f9a30887c0602afc3e16ccb64ed3749be911d82
+  data.tar.gz: a5562501103ac3be5d475216c7c1ae45c5f4c1e519105dcdd8adf1250fe5184a
 SHA512:
-  metadata.gz: 0b7550126e529e67d821042f6fa5d2092f8e93460d4b6e892fe9d21e7bd4e7e5f83673beb39557dafbb1617eb7527569c2b4347e57cf6ce61090e1c00979d335
-  data.tar.gz: 452fc65024f99d80bddf2254e2177a4397b816525d43cf8e42c7e914b95706c4f1a5b4086e5a2e2135792cfe895edcd9dca9e39190c95c74c63cee1550a0da41
+  metadata.gz: 0140e9330cff62dc983f91a5a851cbfc3d188d3711537304e538d3ea8664d7cfebc76d9f19596db60f51b9d23f117f18ec44e9fcebb5dfdf6e72131a8b87b8f6
+  data.tar.gz: 7605cf138cf69f8e7b1cf3f8e7e06c837623e1720c558b85f345bb02eb8da07b48c4882a8822ec6e7c9992756a8cb1d04089a27164e71374a26e1f3784e07943

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### 1.1.1
+### 1.2.0
 
 ### 0.0.1 / 2023-03-23
 

data/Manifest.txt

@@ -4,7 +4,10 @@ README.md
 Rakefile
 lib/ordinals.rb
 lib/ordinals/api.rb
+lib/ordinals/cache.rb
 lib/ordinals/recursive/composite.rb
 lib/ordinals/recursive/generator.rb
 lib/ordinals/recursive/image.rb
+lib/ordinals/sandbox.rb
 lib/ordinals/stats.rb
+lib/ordinals/version.rb

data/README.md

@@ -13,12 +13,15 @@ ordinals gem - ordinals (inscription) api wrapper & helpers for Bitcoin, Litcoin
 
 
 For now ordinal inscription api queries are supported on
-- Bitcoin  (via <https://ordinals.com>)
-- Litecoin (via <https://ordinalslite.com>) and
-- Dogecoin (via <https://doginals.com>)
+- Bitcoin  (via <https://ordinals.com>) and
+- Litecoin (via <https://ordinalslite.com>) 
 
+<!--
+  chekc if doginals still in operation???
+- Dogecoin (via <https://doginals.com>)
+-->
 
-Let's start querying for bitcoin (btc) ordinal inscriptions:
+Let's start querying for bitcoin (btc) ordinal inscriptions by id:
 
 ``` ruby
 require 'ordinals'
@@ -44,20 +47,50 @@ pp data
 #    "address"=>"bc1pyncs638hxfhaqjvnedw2lyc2jta6zuvr9erj6m9cwlghp6qqwvhqeq574l",
 #    "output value"=>"9667",
 #    "sat"=>"1391087135005306",
-#    "preview"=>"link",
-#    "content"=>"link",
-#    "content length"=>"3072 bytes",
-#    "content type"=>"image/png",
+#    "content-length"=>"3072 bytes",
+#    "content-type"=>"image/png",
 #    "timestamp"=>"2023-02-18 03:02:18 UTC",
-#    "genesis height"=>"777099",
-#    "genesis fee"=>"1814",
-#    "genesis transaction"=>"c41021cb11dce003e6a20a3420cf5954a1d104a1fe314393b915a62f020dcd0a",
+#    "genesis-height"=>"777099",
+#    "genesis-fee"=>"1814",
+#    "genesis-transaction"=>"c41021cb11dce003e6a20a3420cf5954a1d104a1fe314393b915a62f020dcd0a",
 #    "location"=>"6a57dedb854c9bcac3fd2daab1172dd9a45f24c366dd8db33fe80557f11c6b39:22:0",
 #    "output"=>"6a57dedb854c9bcac3fd2daab1172dd9a45f24c366dd8db33fe80557f11c6b39:22",
 #    "offset"=>"0"}
 ```
 
 
+Or by number (starting at 0):
+
+``` ruby
+data = Ordinals.inscription( 21_000_000 )
+pp data
+# GET https://ordinals.com/inscription/4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2i0...
+#=> {"title"=>"Inscription 21000000",
+#    "id"=>"4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2i0",
+#    "address"=>"bc1qq7dx8c9842jm6kf4gn83mft07jqtvye0gm5sq9",
+#    "output-value"=>"330",
+#    "sat"=>"1894095647358032",
+#    "content-length"=>"57 bytes",
+#    "content-type"=>"text/plain",
+#    "timestamp"=>"2023-08-02 11:00:22 UTC",
+#    "genesis-height"=>"801343",
+#    "genesis-fee"=>"842",
+#    "genesis-transaction"=>"4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2",
+#    "location"=>"4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2:0:0",
+#    "output"=>"4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2:0",
+#    "offset"=>"0"}
+
+content = Ordinals.content( 21_000_000 )
+pp content
+# GET https://ordinals.com/content/4825a59486fa91ee88b6dd58caf0f9ba0f7273e2f30d9eccf9bfdabee55028d2i0...
+#=> <Ordinals::Api::Content:0x0000028bd4c1ff18
+#     @data="{\"p\":\"brc-20\",\"op\":\"mint\",\"tick\":\"sats\",\"amt\":\"99999999\"}",
+#     @length=nil,
+#     @type="text/plain">
+```
+
+
+
 Let's try querying for litecoin (ltc) ordinal inscriptions:
 
 ``` ruby
@@ -83,18 +116,43 @@ pp data
 #=> {"title"=>"Inscription 642",
 #    "id"=>"f2b6adf7b2d0f128fb14817ff37f5f36e9176b17571e20c49871875553f937b4i0",
 #    "address"=>"LSDz4fM4mLFyAZVoDuKyMHYq3af6cSZGSY",
-#    "output value"=>"9878",
-#    "preview"=>"link",
-#    "content"=>"link",
-#    "content length"=>"816 bytes",
-#    "content type"=>"image/png",
+#    "output-value"=>"9878",
+#    "content-length"=>"816 bytes",
+#    "content-type"=>"image/png",
 #    "timestamp"=>"2023-02-21 05:29:33 UTC",
-#    "genesis height"=>"2426201",
-#    "genesis fee"=>"361",
-#    "genesis transaction"=>"f2b6adf7b2d0f128fb14817ff37f5f36e9176b17571e20c49871875553f937b4",
+#    "genesis-height"=>"2426201",
+#    "genesis-fee"=>"361",
+#    "genesis-transaction"=>"f2b6adf7b2d0f128fb14817ff37f5f36e9176b17571e20c49871875553f937b4",
 #    "location"=>"6802c71b49f18aab91d0b363762b24afb1bf00c4820a5f782de6dd1b1cfbd68a:0:0",
 #    "output"=>"6802c71b49f18aab91d0b363762b24afb1bf00c4820a5f782de6dd1b1cfbd68a:0",
 #    "offset"=>"0"}
+
+
+content = Ordinals.content( 0 )
+pp content
+# GET https://ordinalslite.com/content/71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0eei0...
+#=> <Ordinals::Api::Content:0x00000242a9a874e0
+#     @data="%PDF-1.3\...",
+#     @length=nil,
+#     @type="application/pdf">
+
+data = Ordinals.inscription( 0 )
+pp data
+# GET https://ordinalslite.com/inscription/71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0eei0...
+#=> {"title"=>"Inscription 0",
+#    "id"=>"71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0eei0",
+#    "address"=>"ltc1qz7qy4m8nhfqggxrtj308njs52lu9f5l9v7d5wd",
+#    "output-value"=>"10000",
+#    "sat"=>"906691404536244",
+#    "content-length"=>"57237 bytes",
+#    "content-type"=>"application/pdf",
+#    "timestamp"=>"2023-02-19 20:26:43 UTC",
+#    "genesis-height"=>"2425370",
+#    "genesis-fee"=>"15968",
+#    "genesis-transaction"=>"71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0ee",
+#    "location"=>"71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0ee:0:0",
+#    "output"=>"71e0f6dc87a473aa69787fff8e09e5eddfdca96e587928a5b1a25c0ae16dc0ee:0",
+#    "offset"=>"0"}
 ```
 
 That's it.
@@ -267,7 +325,7 @@ composite = RecursiveImageComposite.new( 10, 10, width: 96,
 data = read_json( "./ordinalpunks.json" )
 puts "  #{data['items'].size} inscribe(s)"
 
-data['items'].each_with_index do |rec|
+data['items'].each do |rec|
    id      = rec['inscription_id']
    comment = rec['name'] 
 
@@ -353,7 +411,7 @@ Use it as you please with no restrictions whatsoever.
 ## Questions? Comments?
 
 Join us in the [Ordgen / ORC-721 discord (chat server)](https://discord.gg/dDhvHKjm2t). Yes you can.
-Your questions and commetary welcome.
+Your questions and commentary welcome.
 
 
 Or post them over at the [Help & Support](https://github.com/geraldb/help) page. Thanks.

data/Rakefile

@@ -1,4 +1,5 @@
 require 'hoe'
+require './lib/ordinals/version.rb'
 
 
 ###
@@ -10,7 +11,7 @@ require 'hoe'
 
 Hoe.spec 'ordinals' do
 
-  self.version = '1.1.1'
+  self.version = Ordinals::VERSION
 
   self.summary = 'ordinals gem - ordinals (inscription) api wrapper & helpers for Bitcoin, Litecoin, Dogecoin & co.'
   self.description = summary

data/lib/ordinals/api.rb

@@ -24,9 +24,13 @@ class Api   ## change/rename Api to Client - why? why not?
   end
 
 
+  def config() Ordinals.config; end  ## convenience shortcut helper
+
   def initialize( base, inscription: 'inscription' )
-    @base        = base
-    @inscription = inscription
+    @base          = base
+    @inscription   = inscription
+    @requests      = 0  ## count requests (for delay_in_s sleeping/throttling)
+    @pages = {}   ## (0-)99, (100-)199, (200-)299 etc.  
   end
 
 
@@ -46,8 +50,9 @@ class Content
 end  ## (nested) class Content
 
 
+  def content( num_or_id )
+     id =  num_or_id.is_a?( Integer ) ? _num_to_id( num_or_id ) : num_or_id 
 
-  def content( id )
      src = "#{@base}/content/#{id}"
      res = get( src )
 
@@ -67,6 +72,56 @@ end  ## (nested) class Content
   end
 
 
+  INSCRIBE_ID_RX = %r{
+    inscription/(?<id>[a-fi0-9]+)
+   }ix
+
+
+  def inscription_ids( offset: )  ## note: page size is for now fixed 100
+    ids = []
+
+    src = "#{@base}/inscriptions/#{offset}"
+    res = get( src )
+
+    page = res.text  ### assumes utf-8 for now
+    page.scan( INSCRIBE_ID_RX ) do |_|
+      m = Regexp.last_match
+      ids << m[:id]
+    end       
+    puts "   #{ids.size} inscribe id(s)"
+    ids = ids.reverse  ## assume latest inscribe id is on top (reverse)
+    ids
+  end
+
+  def sub10k_ids
+    ids = []
+    limit  = 100
+
+    100.times do |i|   ## fetch first hundred (100*100=10000) inscribe ids
+      offset = 99 + limit*i
+      puts "==> #{i} - @ #{offset}..."
+      ids += inscription_ids( offset: offset )
+    end
+    puts "   #{ids.size} inscribe id(s) - total"
+    ids
+  end
+
+  
+  def _num_to_id( num )
+    limit = 100
+    page, i =  num.divmod( limit )
+    offset = 99+limit*page
+    ## e.g.   100.divmod( 100 ) => [1,0]
+    ##        100.divmod( 100 ) => [0,0]
+    ##        99.divmod( 100 ) =>  [0,99]
+    ## etc.
+  
+    ## auto-add to page cache
+    ids =  @pages[ offset ] ||= inscription_ids( offset: offset )      
+    ids[i] 
+   end
+ 
+ 
 =begin
 <dl>
   <dt>id</dt>
@@ -158,7 +213,9 @@ offset: 0
 
 =end
 
-  def inscription( id )
+  def inscription( num_or_id )
+    id =  num_or_id.is_a?( Integer ) ? _num_to_id( num_or_id ) : num_or_id 
+
     src = "#{@base}/#{@inscription}/#{id}"
     res = get( src )
 
@@ -203,14 +260,34 @@ offset: 0
         data[ k ] = v
     end
     data
+
+
+   ## post process to convert to headers format
+   ##   e.g. replace space with -
+   ##   and remove/exclude content & preview
+   h = {}
+   data.each do |k,v|
+      next if ['preview', 'content'].include?( k )
+      h[ k.gsub( ' ', '-') ] = v
+   end
+   h
   end
 
 
   def get( src )
+    @requests += 1
+
+    if @requests > 1 && config.delay_in_s
+      puts "request no. #{@requests}@#{@base}; sleeping #{config.delay_in_s} sec(s)..."
+      sleep( config.delay_in_s )
+    end
+
     res = Webclient.get( src )
+ 
     if res.status.ok?
       res
     else
+      ## todo/fix: raise exception here!!!!
       puts "!! ERROR - HTTP #{res.status.code} #{res.status.message} - failed web request >#{src}<; sorry"
       exit 1
     end

data/lib/ordinals/cache.rb

@@ -0,0 +1,208 @@
+
+module Ordinals
+
+class Cache
+
+def initialize( dir )
+  @dir   = dir   
+  @force = false
+  @delay_in_s = 0.5  ## wait 0.5s before next (possible) request
+  @requests = 0
+end
+
+
+
+def json_to_txt( data )
+  buf = ''
+  data.each do |k,v|
+    next if ['preview', 'content'].include?( k )
+    buf << "#{k.gsub( ' ', '-')}: #{v}\n"
+  end
+  buf
+end
+
+
+
+def _find_blobs
+  ## note:  *.{txt,json,png} will also include *.meta.txt
+  ###            CANNOT use, thus, try *i?.*
+  Dir.glob( "#{@dir}/**/*i?.{txt,json,png}" )
+end
+
+def _find_meta
+  Dir.glob( "#{@dir}/**/*.meta.txt" ) 
+end
+
+def stats
+  paths = _find_meta
+  puts "  #{paths.size} inscribe metadatafile(s) found"
+
+  paths = _find_blobs
+  puts "  #{paths.size} inscribe blob(s) found"
+end
+
+
+
+
+
+
+def add( id )
+   ## step 1)  get metadata records
+   meta_path    = "#{@dir}/#{id[0,2]}/#{id[2..-1]}.meta.txt"
+      
+   meta = nil
+   if !@force && File.exist?( meta_path )
+      meta = read_headers( meta_path )
+      print "."
+   else
+      print " meta-#{id} "
+      sleep( @delay_in_s )   if @delay_in_s && @requests > 0 
+ 
+      ## fetch and cache in cache
+      meta = Ordinals.inscription( id )
+      pp meta
+      meta_txt = json_to_txt( meta )
+      
+      write_text( meta_path, meta_txt )
+      @requests += 1
+   end
+      
+      
+   content_type = meta['content-type']
+   extname =  if content_type.start_with?( 'text/plain' )
+                '.txt'
+              elsif content_type.start_with?( 'application/json' )
+                '.json'
+              elsif content_type.start_with?( 'image/png' )
+                '.png'
+              else
+                puts "!! ERROR - unexpected content type; got: #{content_type}"
+                ## pp meta
+                exit 1
+              end
+      
+      
+   path    = "#{@dir}/#{id[0,2]}/#{id[2..-1]}#{extname}"
+   if !@force && File.exist?( path )
+       ## puts "  in cache"
+       print "."
+   else
+       print " blob-#{id} "
+       sleep( @delay_in_s )   if @delay_in_s && @requests > 0 
+       
+       ## note: save text as blob - byte-by-byte as is  (might be corrupt text)
+       content = Ordinals.content( id )
+       ##  pp content
+       ## puts "data:"
+       ## puts content.data
+      
+       write_blob( path, content.data )
+   end
+end # method add
+
+
+def _prepare_csv( path )
+  ids = []
+  recs = read_csv( path )
+  recs.each do |rec|
+    ids << rec['id']
+  end
+  ids
+end
+
+def add_csv( path )
+  ids = _prepare_csv( path )
+  ids = ids.uniq  ## make uniq by default - why? why not?
+  puts "   #{ids.size} inscribe id(s)"
+  ids.each { |id| add(id) } 
+end
+
+
+
+## get inscription  links
+## e.g.
+##    inscription/e8830c5fbdfc2f529350fd04a2ac20bb097dce98f159223837513ae3c8d05714i0
+
+=begin
+INSCRIBE_ID_RX = %r{
+              /b   # boundry (non-alphanum)
+                 (?<id>[a-f0-9]{64}i[0-9])
+              /b   # boundry (non-alphanum)
+            }ix
+=end
+
+INSCRIBE_ID_RX = %r{
+                  inscription/(?<id>[a-fi0-9]+)
+                 }ix
+
+
+##
+## strict rx gets:
+##  168 inscribe id(s)
+## 118 inscribe id(s) - unique
+##
+##  loose gets:
+##   300 inscribe id(s)
+##   250 inscribe id(s) - unique
+##
+##  /b for boundray NOT working - why? why not?
+
+
+def _prepare_html( path )
+    ids = []
+    txt = read_text( path )
+    txt.scan( INSCRIBE_ID_RX ) do |_|
+      m = Regexp.last_match
+    
+      ids  << m[:id]
+    end
+    ids
+end
+
+def add_html( path )
+    ids = _prepare_html( path )
+    ids = ids.uniq  ## make uniq by default - why? why not?
+    puts "   #{ids.size} inscribe id(s)"
+    ids.each { |id| add(id) } 
+end
+
+def _prepare_dir( dir )
+    ids = []
+
+   ## in html format
+   pages = Dir.glob( "#{dir}/**/*.html")
+   pages.each do |path|
+     ids += _prepare_html( path )
+   end
+      
+   ### in csv format
+   datasets = Dir.glob( "#{dir}/**/*.csv")
+   datasets.each do |path|
+     ids += _prepare_csv( path )
+   end
+      
+   ids
+end
+
+def add_dir( dir )
+    ids = _prepare_dir( dir )
+    puts "   #{ids.size} inscribe id(s)"      
+    ## turn into symbol (to make uniq work ??)
+    ids = ids.uniq
+    pp ids
+    puts "   #{ids.size} inscribe id(s) - unique"
+    ids.each { |id| add(id) } 
+end
+
+
+
+def read( id )
+  _read_inscribe( "#{@dir}/#{id[0,2]}/#{id[2..-1]}.meta.txt" ) 
+end
+
+def _read_inscribe( path )
+  read_headers( path ) 
+end
+
+end # class Cache
+end  # module Ordinals

data/lib/ordinals/sandbox.rb

@@ -0,0 +1,127 @@
+
+
+module Ordinals
+class Sandbox
+   def initialize( dir='./content' )
+      @dir   = dir
+      @force      = false
+      @delay_in_s = 0.5  ## wait 0.5s before next (possible) request
+      @requests = 0
+   end   
+
+
+   def exist?( id )   ### add alias for different name(s) - why? why not?
+     path = "#{@dir}/#{id}"
+     File.exist?( path )
+   end
+
+   def read( id )
+     path = "#{@dir}/#{id}"
+     read_blob( path )
+   end
+
+   def add( id )
+      path = "#{@dir}/#{id}"
+      if !@force && File.exist?( path )
+         ## puts "  in sandbox"
+      else
+        sleep( @delay_in_s )   if @delay_in_s && @requests > 0 
+        
+        ## note: save text as blob - byte-by-byte as is  (might be corrupt text)
+        content = Ordinals.content( id )
+        ## pp content
+        #=> #<Ordinals::Api::Content:0x000001a1352df938
+        #      @data="RIFF\xF8\v\x00\x00WEBPVP8 \xEC\v\x00\x00...",
+        #      @length=3072,
+        #      @type="image/png"
+  
+        ## puts "data:"
+        ## puts content.data
+        write_blob( path, content.data )
+        @requests += 1
+      end
+   end
+
+
+   def add_csv( path )
+      recs = read_csv( path )
+      puts "  #{recs.size} record(s)"
+ 
+      recs.each_with_index do |rec,i|
+        id = rec['id']
+        puts "==> #{i+1}/#{recs.size} - #{id}..."
+        add( id )
+      end
+   end
+
+   def add_collection( path )
+      data = read_json( path )
+      puts "  #{data['items'].size} record(s)"
+
+      data['items'].each_with_index do |rec,i|
+        name = rec['name']
+        id   = rec['inscription_id']
+        puts "==> #{i+1}/#{data['items'].size} - #{name} @ #{id}..."
+        add( id )
+      end
+   end
+
+
+   
+   ID_RX = /[a-f0-9]{64}i[0-9]/x
+
+   def _find_ids( values )
+      values.select { |val| val.is_a?(String) && ID_RX.match(val) }      
+   end
+
+   def add_data( obj )
+      if obj.is_a?( Array )
+         recs = obj
+         puts "  #{recs.size} record(s)"
+         recs.each_with_index do |rec,i|
+              if rec.is_a?( String )
+                  id = rec
+                  puts "==> #{i+1}/#{recs.size} #{id}..."
+                  add( id ) 
+              else  ## assume array of strings for now
+                  values = rec
+                print "==> #{i+1}/#{recs.size} "
+                ids = _find_ids( values )
+                if ids.size == 1
+                  id = ids[0]
+                  puts " #{id}..."
+                  add( id )
+                else 
+                  puts
+                  if ids.empty?
+                    puts "!! ERROR - no inscribe id found in data row:"
+                  else
+                    puts "!! ERROR - more than one (that is, #{ids.size}) inscribe id found in data row:"
+                  end
+                  pp values
+                  exit 1
+                end
+              end
+         end        
+      else
+        ## todo/fix: raise ArgumentError - why? why not?
+        puts "!! ERROR - sorry"
+        exit 1
+      end
+   end
+
+ # todo/add  
+ #  def add_html( path )
+ #  end
+
+
+   def add_dir( rootdir )
+      ## glob for **.csv and **.html
+      datasets = Dir.glob( "#{rootdir}/**/*.csv" )
+      datasets.each do |path|
+         add_csv( path )
+      end
+   end
+end  ## class Sandbox
+end  ## module Ordinals
+

data/lib/ordinals/version.rb

@@ -0,0 +1,20 @@
+
+module Ordinals
+  # sync version w/ sport.db n friends - why? why not?
+  MAJOR = 1 ## todo: namespace inside version or something - why? why not??
+  MINOR = 2
+  PATCH = 0
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "ordinals/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in >#{root}<"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )
+  end
+end

data/lib/ordinals.rb

@@ -5,6 +5,49 @@ require 'nokogiri'
 
 
 
+### todo/fix:
+###   move upstream  - read_headers
+
+##
+#  note: key only supports a-z0-9 AND dash(-)
+#    no underscore(_) or dot(.)
+#
+#  follow HTTP headers and domain names format
+##
+
+HEADER_RX = /\A(?<key>[a-z][a-z0-9-]*)
+                 :
+                 [ ]*
+               (?<value>.+?)    ## non-greedy
+              \z
+             /x
+
+
+def read_headers( path )
+  txt = read_text( path )
+  h = {}
+  txt.each_line do |line|
+    line = line.strip
+    ## skip empty and comment lines
+    next if line.empty? || line.start_with?( '#' )
+
+    if m=HEADER_RX.match(line)
+      key   = m[:key]
+      value = m[:value]
+      
+      h[key] = value
+   else 
+      puts "!! ERROR - parse error - no header pattern match for:"
+      puts line
+      exit 1
+   end
+  end
+  h
+end
+
+
+
+
 
 module Ordinals
   class Configuration
@@ -43,6 +86,15 @@ module Ordinals
       self.chain = 'btc'   unless defined?( @client )
       @client
     end
+
+    def delay_in_s 
+      ## note - default to 1 (sec) if not set
+      self.delay_in_s = 1   unless defined?( @delay_in_s )
+      @delay_in_s
+    end  
+    def delay_in_s=(value) @delay_in_s = value; end
+    alias_method :sleep,  :delay_in_s   ## add sleep alias (or wait) - why? why not?
+    alias_method :sleep=, :delay_in_s=
   end # class Configuration
 
 
@@ -76,15 +128,22 @@ module Ordinals
 
   ###################
   ### more convenience shortcuts
-  def self.inscription( id ) client.inscription( id ); end
-  def self.content( id )     client.content( id );     end
+  def self.inscription( num_or_id )             client.inscription( num_or_id ); end
+  def self.content( num_or_id )                 client.content( num_or_id );     end
+
+  def self.inscription_ids( offset: )    client.inscription_ids( offset: offset ); end
+  def self.sub10k_ids()                  client.sub10k_ids; end
 end  # module Ordinals
 
 
 
 
 ## our own code
+require_relative 'ordinals/version'
 require_relative 'ordinals/api'
+
+require_relative 'ordinals/cache'
+require_relative 'ordinals/sandbox'   ## (blob) "flat" content cache by inscribe id (./content)
 require_relative 'ordinals/stats'
 
 
@@ -98,3 +157,7 @@ require_relative 'ordinals/recursive/generator'
 RcsvImage          = RecursiveImage
 RcsvImageComposite = RecursiveImageComposite
 
+
+
+# say hello
+puts Ordinals.banner     ## if defined?($RUBYCOCOS_DEBUG) && $RUBCOCOS_DEBUG

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ordinals
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-21 00:00:00.000000000 Z
+date: 2023-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocos
@@ -88,10 +88,13 @@ files:
 - Rakefile
 - lib/ordinals.rb
 - lib/ordinals/api.rb
+- lib/ordinals/cache.rb
 - lib/ordinals/recursive/composite.rb
 - lib/ordinals/recursive/generator.rb
 - lib/ordinals/recursive/image.rb
+- lib/ordinals/sandbox.rb
 - lib/ordinals/stats.rb
+- lib/ordinals/version.rb
 homepage: https://github.com/ordbase/ordbase
 licenses:
 - Public Domain