ethscribe 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 188cf1ce52483f1154cb3ecf9bc7bbb4fcd60afa3d74543a0e1523c29e866e59
-  data.tar.gz: c9c60dbdc3ffb69b23447a3e44e33c28788b156aed6c4f40571a9a91a3f2d1b0
+  metadata.gz: '09ac9a5eb1dbb35dde2105a3865bf6c67edd5469e8f9518e46949752f127991a'
+  data.tar.gz: 81e37a9c8a75bf4b1ec7a7ac82feccee8906a4a45636c750f7ba54e8c3797334
 SHA512:
-  metadata.gz: d98ebfe511ec43d963697e487a3202641d16c1a1ab51b0d8239f3cd0d4a8cd2c7f939bb2b98046dcb615f475fe8f3caabbbdecfbd18b46471bb3d3b53ded6eaa
-  data.tar.gz: 84139161c630e77dc0f20cbf0e538394179b265af5ba4b739cbc5b8efa72f857ebd36dbdd09976262d8cbfebbfb09b1f3ec55b7f859141a99df38b15777d44b1
+  metadata.gz: 5cc33bb70781c8490fb1f5c8c3512f22d614fa6eade666d90ec7c1e7e30a77559e42a77f0bbaa28518111b1b1b0da498c764b9627d31488e0aab3d7788919f3b
+  data.tar.gz: 73547597a38a756b3be3dcf8d11ee387e651dffdfea3db936f250a146288bdc74b5a7f2d575e1a9eccce9e21b1b204591e4df8436601656f35780866a29afa06

data/CHANGELOG.md

@@ -1,3 +1,4 @@
+### 0.2.0
 ### 0.0.1 / 2023-11-20
 
 * Everything is new. First release

data/Manifest.txt

@@ -3,3 +3,5 @@ Manifest.txt
 README.md
 Rakefile
 lib/ethscribe.rb
+lib/ethscribe/api.rb
+lib/ethscribe/version.rb

data/README.md

@@ -1,6 +1,6 @@
-# Ethscribe - Inscription (Ethscription Calldata) API Wrapper & Helpers for Ethereum & Co.
+# Ethscribe - Inscription / Inscribe (Ethscription Calldata) API Wrapper & Helpers for Ethereum & Co.
 
-ethscribe  -  inscription (ethscription calldata) api wrapper & helpers for Ethereum & co.
+ethscribe  -  inscription / inscribe (ethscription calldata) api wrapper & helpers for Ethereum & co.
 
 
 
@@ -10,13 +10,95 @@ ethscribe  -  inscription (ethscription calldata) api wrapper & helpers for Ethe
 * rdoc  :: [rubydoc.info/gems/ethscribe](http://rubydoc.info/gems/ethscribe)
 
 
-## What's Ethscription Calldata / Ethereum Inscription?!
 
-To be done...
+## What's Ethscription Calldata - Ethereum Inscription / Inscribe?!
 
+See [Introducing Ethscriptions - A new way of creating and sharing digital artifacts on the Ethereum blockchain using transaction calldata »](https://medium.com/@dumbnamenumbers/introducing-ethscriptions-698b295d6f2a)
 
 
 
+## Usage
+
+This is a little "lite" wrapper around the ethscriptions.com api(s).
+
+
+> The Ethscriptions.com API (v1) 
+> does not require a key, however it is rate limited. 
+> If you need more throughput, contact Middlemarch on Twitter.
+>
+> If you build something cool, also contact Middlemarch on Twitter!
+>
+> There is a goerli API and a mainnet API. The base URIs are:
+>
+> - https://goerli-api.ethscriptions.com/api
+> - https://mainnet-api.ethscriptions.com/api
+> 
+> Append the below paths, plus a query string if you want, to access the API!
+>
+> -- [Introducing the Ethscriptions.com API (v1)](https://medium.com/@dumbnamenumbers/introducing-the-ethscriptions-com-api-v1-6d2c507d82cd)
+
+
+
+The (ethereum) goerli testnet api is wrapped in `Ethscribe::Api.goerli` and
+the (ethereum) mainnet api is wrapped in `Ethscribe::Api.mainnet`.
+
+Let's try the mainnet:
+
+```ruby
+require 'ethscribe'
+
+web = Ethscribe::Api.mainnet    # or Ethscribe::Api.goerli
+
+
+## get latest 25 inscriptions (defaults: page_size=25, sort_order=desc)
+pp web.ethscriptions
+
+## get inscriptions page 1 (same as above)
+pp web.ethscriptions( page: 1 ) 
+
+# get inscriptions page 2
+pp web.ethscriptions( page: 2 ) 
+
+# get oldest first  - sort_order=asc
+pp web.ethscriptions( page: 1, sort_order: 'asc' ) 
+pp web.ethscriptions( page: 2, sort_order: 'asc' ) 
+
+
+# get inscription by id or num
+pp web.ethscription( 0 ) 
+pp web.ethscription( 1 ) 
+pp web.ethscription( 1000 ) 
+pp web.ethscription( 1_000_000 ) 
+
+
+# get inscriptions owend by <addresss>
+address = '0x2a878245b52a2d46cb4327541cbc96e403a84791'
+pp web.ethscriptions_owned_by( address ) 
+
+
+# get inscription (decoded) content_data and content_type by id or num 
+pp web.ethscription_data( 0 ) 
+pp web.ethscription_data( 1 ) 
+pp web.ethscription_data( 2 ) 
+
+
+# check if content exists (using sha256 hash)
+# inscribe no. 0
+sha = '2817fd9cf901e4435253881550731a5edc5e519c19de46b08e2b19a18e95143e'
+pp web.ethscription_exists( sha ) 
+
+# inscribe no. ??
+sha = '2817fd9cf901e4435253833550731a5edc5e519c19de46b08e2b19a18e95143e'
+pp web.ethscription_exists( sha )  
+
+# check the indexer (block) status
+pp web.block_status
+```
+
+
+That's it for now.
+
+
 
 ## Bonus - More Blockchain (Crypto) Tools, Libraries & Scripts In Ruby
 

data/Rakefile

@@ -1,11 +1,11 @@
 require 'hoe'
-# require './lib/ethscribe/version.rb'
+require './lib/ethscribe/version.rb'
 
 
 Hoe.spec 'ethscribe' do
-  self.version = '0.0.1'   
+  self.version = Ethscribe::VERSION
 
-  self.summary = 'ethscribe  -  inscription (ethscription calldata) api wrapper & helpers for Ethereum & co.'
+  self.summary = 'ethscribe - inscription / inscribe (ethscription calldata) api wrapper & helpers for Ethereum & co.'
   self.description = summary
 
   self.urls    = { home: 'https://github.com/s6ruby/rubidity' }
@@ -18,6 +18,7 @@ Hoe.spec 'ethscribe' do
   self.history_file = 'CHANGELOG.md'
 
   self.extra_deps = [
+    ['cocos'],   
   ]
 
   self.licenses = ['Public Domain']

data/lib/ethscribe/api.rb

@@ -0,0 +1,190 @@
+
+
+module Ethscribe
+
+
+class Api   ## change/rename Api to Client - why? why not?
+  def self.goerli
+    @goerli ||= new( 'https://goerli-api.ethscriptions.com/api' )
+    @goerli
+  end
+  ## todo: add test alias - why? why not? 
+
+  def self.mainnet
+    @mainnet ||= new( 'https://api.ethscriptions.com/api' )
+    @mainnet
+  end
+  ## todo:  add eth, main or production alias - why? why not?
+
+
+  def config() Ethscribe.config; end  ## convenience shortcut helper
+
+
+  def initialize( base )
+    @base          = base
+    @requests      = 0  ## count requests (for delay_in_s sleeping/throttling)
+  end
+
+
+# 
+#  Get all ethscriptions
+#
+#  /ethscriptions
+#  
+#  Query parameters: 
+#   page       - integer  (starting at 1)
+#   per_page   - integer    (default: 25 - max: 50)
+#   sort_order - string "asc" or "desc"   (default: desc - latest first)
+
+
+  def ethscriptions( page: nil, per_page: nil, sort_order: nil )  
+    src = "#{@base}/ethscriptions"
+    params = []
+    params << ['page',       page.to_s]                    if page 
+    params << ['per_page',   per_page.to_s]                if per_page 
+    params << ['sort_order', sort_order.to_s.downcase ]    if sort_order
+    
+    if params.size > 0
+         src += "?" + params.map { |key,value| "#{key}=#{value}" }.join('&')
+    end
+
+    res = get( src )
+    res.json   ## return parsed json data - why? why not?
+  end
+
+#  
+#  Get ethscriptions owned by address
+#
+#  /ethscriptions/owned_by/:address
+#  
+#  Query parameters: page, per_page( max 1000), sort_order (asc / desc)
+
+def ethscriptions_owned_by( address )  
+  src = "#{@base}/ethscriptions/owned_by/#{address}"
+ 
+  res = get( src )
+  res.json   ## return parsed json data - why? why not?
+end
+
+
+
+#
+#  Get specific ethscription
+#
+#  /ethscriptions/:ethscription_id
+#  
+#  Or
+#  
+#  /ethscriptions/:ethscription_number
+#  
+#  (ethscription_id is the transaction hash of the transaction that created the ethscription)
+
+  # note: use singular (overload method by args not possible in ruby)
+  def ethscription( id_or_num )  
+    src = "#{@base}/ethscriptions/#{id_or_num}"
+    res = get( src )
+    res.json   ## return parsed json data - why? why not?
+  end
+
+#
+#  Get data of an ethscription
+#
+#  /ethscriptions/:ethscription_id/data
+#
+# Or
+#
+# /ethscriptions/:ethscription_number/data
+#
+# This will return the ethscription's raw decoded data in the correct mimetype
+
+
+  ###
+  # use a struct-like content class - why? why not?
+  class Content
+    attr_reader :data,
+                :type,
+                :length
+    def initialize( data, type, length )
+      @data   = data
+      @type   = type
+      @length = length
+    end
+
+    alias_method :blob, :data
+  end  ## (nested) class Content
+
+
+  def ethscription_data( id_or_num )  
+     src = "#{@base}/ethscriptions/#{id_or_num}/data"
+     res = get( src )
+ 
+     content_type   = res.content_type
+     content_length = res.content_length
+
+     ## note - content_length -- returns an integer (number)
+     ## puts "content_length:"
+     ## print content_length.inspect
+     ## print " - #{content_length.class.name}\n"
+
+      ## fix-fix-fix
+      ##  if text/json/svg type etc. 
+      ##  convert to utf8 (from binary blob why? why not?) - why? why not?
+      ##   or add text accessor to content?
+
+     content = Content.new(
+                    res.blob,
+                    content_type,
+                    content_length )
+     content
+  end
+
+
+###
+# Check whether content is already ethscribed
+#
+# /ethscriptions/exists/:sha
+# 
+# Where sha is the sha256 of the UTF-8 data URI
+
+# {"result":false,"ethscription":null}
+
+  def ethscription_exists( sha )
+    src = "#{@base}/ethscriptions/exists/#{sha}"
+    res = get( src )
+    res.json   ## return parsed json data - why? why not?
+  end
+
+# Determine if the indexer is behind 
+#
+#  {"current_block_number":18619883,"last_imported_block":18619883,"blocks_behind":0}
+
+  def block_status
+    src = "#{@base}/block_status"
+    res = get( src )
+    res.json   ## return parsed json data - why? why not?
+  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
+  end
+end  # class Api
+
+
+end   ## module Ethscibe
+

data/lib/ethscribe/version.rb

@@ -0,0 +1,19 @@
+
+module Ethscribe
+  MAJOR = 0 ## 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
+    "ethscribe/#{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/ethscribe.rb

@@ -1,3 +1,94 @@
+require 'cocos'
 
-puts "Hello, Ethscribe!"
+
+
+module Ethscribe
+  class Configuration
+
+    #######################
+    ## accessors
+    def chain=(value)
+        if value.is_a?( String ) || value.is_a?( Symbol )
+            case value.downcase.to_s
+            when 'mainnet'  #  'main', 'eth', 'prod', 'production'
+               @chain  = 'mainnet'
+               @client = Ethscribe::Api.mainnet
+            when 'goerli'   #  'testnet', 'test'
+               @chain = 'goerli'
+               @client = Ethscribe::Api.goerli
+            else
+              raise ArgumentError, "unknown chain - expected mainnet | goerli; got #{value}"
+            end
+        else
+            raise ArgumentError, "only string or symbol supported for now; sorry - got: #{value.inspect} : #{value.class.name}"
+        end
+    end
+
+    def chain
+      ## note - default to mainnet if not set
+      self.chain = 'mainnet'   unless defined?( @chain )
+      @chain
+    end
+
+    ## note: read-only for now - why? why not?
+    def client
+      ## note - default to btc/ if not set
+      self.chain = 'mainnet'   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
+
+
+  ## lets you use
+  ##   Ordinals.configure do |config|
+  ##      config.chain = :btc
+  ##   end
+  def self.configure() yield( config ); end
+  def self.config()    @config ||= Configuration.new;  end
+
+  ##  add some convenience shortcut helpers (no config. required) - why? why not?
+  def self.client()      config.client; end
+  def self.chain()       config.chain; end
+  def self.chain=(value) config.chain = value; end
+
+
+  def self.mainnet?()     config.chain == 'mainnet'; end
+  def self.goerli?()      config.chain == 'goerli'; end
+ 
+
+  ###################
+  ### more convenience shortcuts
+
+  def self.inscribes( **kwargs )  client.ethscriptions( **kwargs ); end
+  def self.inscribe( id_or_num )  client.ethscription( id_or_num ); end
+end  # module Ethscribe
+
+
+
+
+## our own code
+require_relative 'ethscribe/version'
+require_relative 'ethscribe/api'
+
+
+
+module Ethscribe
+  #############
+  ##  add more convenience alias - why? why not?
+  API = Api
+end  # module Ethscribe
+
+
+
+# say hello
+puts Ethscribe.banner     ## if defined?($RUBYCOCOS_DEBUG) && $RUBCOCOS_DEBUG
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ethscribe
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-20 00:00:00.000000000 Z
+date: 2023-11-21 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: cocos
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -44,8 +58,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
-description: ethscribe  -  inscription (ethscription calldata) api wrapper & helpers
-  for Ethereum & co.
+description: ethscribe - inscription / inscribe (ethscription calldata) api wrapper
+  & helpers for Ethereum & co.
 email: gerald.bauer@gmail.com
 executables: []
 extensions: []
@@ -59,6 +73,8 @@ files:
 - README.md
 - Rakefile
 - lib/ethscribe.rb
+- lib/ethscribe/api.rb
+- lib/ethscribe/version.rb
 homepage: https://github.com/s6ruby/rubidity
 licenses:
 - Public Domain
@@ -83,6 +99,6 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: ethscribe  -  inscription (ethscription calldata) api wrapper & helpers for
-  Ethereum & co.
+summary: ethscribe - inscription / inscribe (ethscription calldata) api wrapper &
+  helpers for Ethereum & co.
 test_files: []