ethscribe 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4217cdc814f3b713841774ed4eec4abe0f024d598e365a5b7b34e142f555d77
-  data.tar.gz: a28f4ca71df40a9da404ccc817e2e4ae13b247da8a44ea4878d5fee9e0f54a6b
+  metadata.gz: 54c1bc99feba882f271fdf9e1158cf47c09e4611664d3d2d27fc770e2d3e4882
+  data.tar.gz: 5a0297d9ccb9df224707b34101803a262f21bb63bf2e2debb963913296654551
 SHA512:
-  metadata.gz: e3d408e310e9df8cd9ef4df9376d854f3d243eabd321920071d27d6a94131e03114865427ee36c5dbf97693a1893ba4329d0cd1e56278611519f2f05f4b57185
-  data.tar.gz: 9cb5cb71409a5e8280ea5be41c1c2c07b1ea0602766caee4168decb8a530a3f99931d950f4d28074905505fc76225530a13517126bd57da2f9039a23e93ac050
+  metadata.gz: 3bd5ff76a13b14e43ad80ba4ba742e19bfebf13491f4ad77ec6feeaac636ec8d0b1c90f749e7371812df1e186813a1885001b682ec4ca9ed40acc13bebc41656
+  data.tar.gz: a8477a3ff5e4ced79055b3292f2731eb9088976ddaea275e2fbc8bf23809ea4bbbf8bc52dec9be6014b41cab58038bcb5ac3d9dc301c7be99281625c87e5e21d

data/CHANGELOG.md

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

data/README.md

@@ -1,22 +1,104 @@
-# 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.
 
 
 
-* home  :: [github.com/s6ruby/rubidity](https://github.com/s6ruby/rubidity)
-* bugs  :: [github.com/s6ruby/rubidity/issues](https://github.com/s6ruby/rubidity/issues)
+* home  :: [github.com/0xCompute/ethscribe](https://github.com/0xCompute/ethscribe)
+* bugs  :: [github.com/0xCompute/ethscribe/issues](https://github.com/0xCompute/ethscribe/issues)
 * gem   :: [rubygems.org/gems/ethscribe](https://rubygems.org/gems/ethscribe)
 * 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'
+
+net = Ethscribe::Api.mainnet    # or Ethscribe::Api.goerli
+
+
+# get latest 25 inscriptions (defaults: page_size=25, sort_order=desc)
+pp net.ethscriptions
+
+# get inscriptions page 1 (same as above)
+pp net.ethscriptions( page: 1 ) 
+
+# get inscriptions page 2
+pp net.ethscriptions( page: 2 ) 
+
+# get oldest first  - sort_order=asc
+pp net.ethscriptions( page: 1, sort_order: 'asc' ) 
+pp net.ethscriptions( page: 2, sort_order: 'asc' ) 
+
+
+# get inscription by id or num
+pp net.ethscription( 0 ) 
+pp net.ethscription( 1 ) 
+pp net.ethscription( 1000 ) 
+pp net.ethscription( 1_000_000 ) 
+
+
+# get inscriptions owned by <addresss>
+address = '0x2a878245b52a2d46cb4327541cbc96e403a84791'
+pp net.ethscriptions_owned_by( address ) 
+
+
+# get inscription (decoded) content_data and content_type by id or num 
+pp net.ethscription_data( 0 ) 
+pp net.ethscription_data( 1 ) 
+pp net.ethscription_data( 2 ) 
+
+
+# check if content exists (using sha256 hash)
+# inscribe no. 0
+sha = '2817fd9cf901e4435253881550731a5edc5e519c19de46b08e2b19a18e95143e'
+pp net.ethscription_exists( sha ) 
+
+# inscribe no. ??
+sha = '2817fd9cf901e4435253833550731a5edc5e519c19de46b08e2b19a18e95143e'
+pp net.ethscription_exists( sha )  
+
+# check the indexer (block) status
+pp net.block_status
+```
+
+
+That's it for now.
+
+
 
 ## Bonus - More Blockchain (Crypto) Tools, Libraries & Scripts In Ruby
 
@@ -26,7 +108,9 @@ at the ruby code commons (rubycocos) org.
 
 ## Questions? Comments?
 
-Join us in the [Rubidity (community) discord (chat server)](https://discord.gg/3JRnDUap6y). Yes you can.
+Join us in the [0xCompute discord (chat server)](https://discord.gg/3JRnDUap6y) 
+(or in the more general Ethscription discord). 
+Yes you can.
 Your questions and commentary welcome.
 
 Or post them over at the [Help & Support](https://github.com/geraldb/help) page. Thanks.

data/Rakefile

@@ -5,10 +5,10 @@ require './lib/ethscribe/version.rb'
 Hoe.spec 'ethscribe' do
   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' }
+  self.urls    = { home: 'https://github.com/0xCompute/ethscribe' }
 
   self.author  = 'Gerald Bauer'
   self.email   = 'gerald.bauer@gmail.com'

data/lib/ethscribe/api.rb

@@ -25,10 +25,16 @@ class Api   ## change/rename Api to Client - why? why not?
     @requests      = 0  ## count requests (for delay_in_s sleeping/throttling)
   end
 
-#########
-# page       - integer  (starting at 1)
-# per_page   - integer    (default: 25)
-# sort_order - string "asc" or "desc"   (default: desc - latest first)
+
+# 
+#  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 )  
@@ -39,7 +45,7 @@ class Api   ## change/rename Api to Client - why? why not?
     params << ['sort_order', sort_order.to_s.downcase ]    if sort_order
     
     if params.size > 0
-         src += "?" + params.map { |key,value| "#{key}=#{value}" }.join('&')
+         src += "?" + params.map { |key,value| "#{key}=#{URI.encode_uri_component(value)}" }.join('&')
     end
 
     res = get( src )
@@ -47,6 +53,172 @@ class Api   ## change/rename Api to Client - why? why not?
   end
 
 
+  ####
+  #  ContractTransaction.transaction_mimetype
+  #    "application/vnd.facet.tx+json"
+  #  SystemConfigVersion.system_mimetype
+  #    "application/vnd.facet.system+json"
+  def newer_facet_txs( new_block_number, 
+                       max: 2500,
+                       max_blocks: 10000,
+                       count: 0 )
+    newer_ethscriptions( new_block_number, 
+                           max_ethscriptions: max,
+                           max_blocks: max_blocks,
+                           mimetypes: ['application/vnd.facet.tx+json',
+                                       'application/vnd.facet.system+json'],
+                           count: count
+                         )
+  end
+  alias_method :newer_facet_txns, :newer_facet_txs
+
+  ## add "undocumented" endpoint 
+  ##   /ethscriptions/newer_ethscriptions
+  ##
+  ##  see https://github.com/0xFacet/facet-vm/blob/main/app/models/ethscription_sync.rb
+
+  def newer_ethscriptions( new_block_number, 
+                           max_ethscriptions: 2500,
+                           max_blocks: 10000,
+                           mimetypes: [],
+                           count: 0
+                         )
+    src = "#{@base}/ethscriptions/newer_ethscriptions"
+
+    params = []
+    params << ['block_number', new_block_number.to_s]
+
+    ## note: array MUST use rails convention with []
+    mimetypes.each do |mimetype|
+      params << ['mimetypes[]', mimetype]
+    end
+
+    params << ['max_ethscriptions',  max_ethscriptions.to_s] 
+    params << ['max_blocks', max_blocks.to_s ] 
+    params << ['past_ethscriptions_count', count.to_s]
+ 
+    src += "?" + params.map do |key,value| 
+                     "#{URI.encode_uri_component(key)}=#{URI.encode_uri_component(value)}" 
+                  end.join('&')
+  
+    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
 

data/lib/ethscribe/version.rb

@@ -1,7 +1,7 @@
 
 module Ethscribe
-  MAJOR = 0 ## todo: namespace inside version or something - why? why not??
-  MINOR = 1
+  MAJOR = 1 ## todo: namespace inside version or something - why? why not??
+  MINOR = 0
   PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/lib/ethscribe.rb

@@ -69,6 +69,7 @@ module Ethscribe
   ### 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
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ethscribe
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-21 00:00:00.000000000 Z
+date: 2024-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocos
@@ -50,16 +50,16 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
-description: ethscribe - inscription (ethscription calldata) api wrapper & helpers
-  for Ethereum & co.
+        version: '4.1'
+description: ethscribe - inscription / inscribe (ethscription calldata) api wrapper
+  & helpers for Ethereum & co.
 email: gerald.bauer@gmail.com
 executables: []
 extensions: []
@@ -75,7 +75,7 @@ files:
 - lib/ethscribe.rb
 - lib/ethscribe/api.rb
 - lib/ethscribe/version.rb
-homepage: https://github.com/s6ruby/rubidity
+homepage: https://github.com/0xCompute/ethscribe
 licenses:
 - Public Domain
 metadata: {}
@@ -99,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: []