solidity-typed 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 634cc8c8ee7cf10c3a67c0a8dbcc7c5efad7fe17a5a961128a5140f7648a8ff0
+  data.tar.gz: f6956a85d7b3e7ae5aa021052ddcc9981f0c5f394acb29f0457e2587a3cc8e56
+SHA512:
+  metadata.gz: 9537d4935ea267c3ace17ac3625552fab903dee944718e9163392167c39cdcff478f3494c9780e09db327c6228458dac5d33e3738fddd3fa08463322d9fff99e
+  data.tar.gz: 6210074c6e54f778fca18fbb738f8a884421702ceede73d73e4b5efd32ccce35ea2b30fd7507ed76f0d820753723c735bdd0f3af58ff252b480dfed2c9cf5833

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+### 0.1.0
+### 0.0.1 / 2023-09-10
+
+* Everything is new. First release

data/Manifest.txt

@@ -0,0 +1,24 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/solidity/typed.rb
+lib/solidity/typed/array.rb
+lib/solidity/typed/array_builder.rb
+lib/solidity/typed/bool.rb
+lib/solidity/typed/conversion.rb
+lib/solidity/typed/enum.rb
+lib/solidity/typed/enum_builder.rb
+lib/solidity/typed/mapping.rb
+lib/solidity/typed/mapping_builder.rb
+lib/solidity/typed/metatypes/array.rb
+lib/solidity/typed/metatypes/bool.rb
+lib/solidity/typed/metatypes/literals.rb
+lib/solidity/typed/metatypes/mapping.rb
+lib/solidity/typed/metatypes/types.rb
+lib/solidity/typed/numbers.rb
+lib/solidity/typed/struct.rb
+lib/solidity/typed/struct_builder.rb
+lib/solidity/typed/typed.rb
+lib/solidity/typed/values.rb
+lib/solidity/typed/version.rb

data/README.md

@@ -0,0 +1,318 @@
+# Solidity Typed
+
+solidity-typed - "zero-dependency" 100%-solidity compatible data type and application binary interface (abi) machinery incl. bool, (frozen) string, address, bytes, uint, int, enum, struct, array, mapping, event, and more for solidity-inspired contract (blockchain) programming languages incl. rubidity et al
+
+
+
+
+* home  :: [github.com/s6ruby/rubidity](https://github.com/s6ruby/rubidity)
+* bugs  :: [github.com/s6ruby/rubidity/issues](https://github.com/s6ruby/rubidity/issues)
+* gem   :: [rubygems.org/gems/solidity-typed](https://rubygems.org/gems/solidity-typed)
+* rdoc  :: [rubydoc.info/gems/solidity-typed](http://rubydoc.info/gems/solidity-typed)
+
+
+## What's Solidity?! What's Rubidity?!
+
+See [**Solidity - Contract Application Binary Interface (ABI) Specification** »](https://docs.soliditylang.org/en/latest/abi-spec.html)
+
+See [**Rubidity - Ruby for Layer 1 (L1) Contracts / Protocols with "Off-Chain" Indexer**  »](https://github.com/s6ruby/rubidity)
+
+
+
+
+## Data Types
+
+
+
+### Available Value & Reference Types
+
+Value Types
+
+* `String`: Text-based data (in utf8 encoding). Note: Solditity (-typed) strings are immutable (frozen).
+* `Address`: User or contract (blockchain) address (in hexadecimal) - 20 bytes (40 hexchars).
+* `InscriptionId`: Unique identifiers for inscriptions (in hexadecimal) - 32 bytes (64 hexchars).
+* `Bool`: Boolean values (true or false).
+* `UInt`: Unsigned (natural) 256-bit integer numbers  (0..2^256-1)
+* `Int`: Signed (negative or positive) 256-bit integer numbers.
+* `Timestamp`: Date and time (stored as unsigned 256-bit integers. Seconds since "unix epoch" starting on January 1st, 1970 at 0:00).
+
+
+<!--
+* `:dumbContract`: A specific type of contract ID (hexadecimal).
+* `:addressOrDumbContract`: Either an Ethereum address or a specific type of contract ID.
+-->
+
+
+Reference Types
+
+* `Mapping`: Key-value storage for different types.
+* `Array`: Lists of other types.
+
+
+### Zero (Default) Values
+
+In Solidity, every type comes with a zero (default) value 
+that gets assigned when a variable is declared but not initialized. 
+Understanding these defaults is crucial for avoiding unintended behavior in your code. 
+Here is the rundown:
+
+* **Integers (Int, UInt, Timestamp, Timedelta)**:  Default to `0`.
+* **Address Types (Address)**: Default to a zero-address, which is `0x0000000000000000000000000000000000000000`.
+* **Inscription Identifiers (InscriptionId)**: Default to a zero-identifier, `0x0000000000000000000000000000000000000000000000000000000000000000`.
+* **String (String)**: Default to an empty string `''`.
+* **Boolean (Bool)**: Default to `false`.
+* **Mapping (Mapping)**: Default to an empty mapping object. The key and value types are set according to your specifications.
+* **Array (Array)**: Default to an empty array object. The sub type is set according to your specification.
+
+
+
+### Literals & Type Coercion and Validation
+
+Solidity (-Typed) employs a strong system of type validation and coercion to ensure that variables adhere to their declared types. This involves transforming literal values into the corresponding solidity types and reporting type mismatches.
+
+Here's a brief rundown of type coercion rules:
+
+* **Address**: Accepts hexadecimal strings that match the contract or user (blockchain) address format (`0x` followed by 40 hexadecimal characters). The address is then normalized to lowercase.
+* **UInt and Int**: These types accept both integer and string representations. Strings are attempted to be coerced into integers. uint and int cannot be out of the range of their Solidity counterparts.
+* **String**: Only accepts string literals. Note: strings are immutable (frozen).
+* **Bool**: Accepts only `true` or `false`.
+* **InscriptionId**: Accepts hexadecimal strings matching specific patterns (`0x` followed by 64 hexadecimal characters).
+* **Timestamp**: Relies on `UInt` type coercion, as it's represented as an unsigned integer (32-bit) internally.
+* **Mapping**: Accepts a Hash and ensures that keys and values match the specified types. Coerces these into a typed mapping object (`Mapping`).
+* **Array**: Accepts an array and ensures that the values match the specified type. Coerces these into a typed array object (`Array`).
+
+
+
+
+## Usage
+
+
+Let's try some random use:
+
+
+
+
+``` ruby
+require 'solidity/typed'
+
+
+module Sandbox   ## note: "wrap" in sandbox (auto-)incl. (solidity) types 
+
+#####################################
+#   frozen (immutable ) value types
+
+
+#  note: (typed) strings always use utf-8 encoding AND
+#               are frozen/immutable!!!
+a = String.new                    #=> <val string:"">
+a = String.new( 'hello, world!' ) #=> <val string:"hello, world!">
+
+
+a = UInt.new                      #=> <val uint:0>
+a = UInt.new( 100 )               #=> <val uint:100>
+a += 100                               #=> <val uint:200>
+a -= 100                               #=> <val uint:100>
+
+#  use/add TypedNat(ural) (natural integer number) alias - why? why not?
+#    check if natural numbers start at 0 (or exclude 0 ????)
+
+a = Int.new                       #=> <val int:0>
+a = Int.new( 100 )                #=> <val int:100>
+a += 100                               #=> <val int:200>
+a -= 100                               #=> <val int:100>
+
+# 
+#  idea  - use "plain" integer as TypedInt - why? why not?
+
+
+a  = false                            #=> <val bool:false>
+a  = true                             #=> <val bool:true>
+
+# 
+#  idea - use "plain" true|false  as TypedBool (frozen|typed) - done
+
+
+a = Address.new
+#=> <val address:"0x0000000000000000000000000000000000000000">
+a = Address.new( '0x'+ 'aa'*20 )
+#=> <val address:"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa">
+
+
+a = InscriptionId.new
+#=> <val inscriptionId:"0x0000000000000000000000000000000000000000000000000000000000000000">
+a = InscriptionId.new( '0x'+'ab'*32 )
+#=> <val inscriptionId:"0xabababababababababababababababababababababababababababababababab">
+
+
+a = Bytes32.new
+#=> <val bytes32:"0x0000000000000000000000000000000000000000000000000000000000000000">
+a = Bytes32.new( '0x'+'ab'*32 )
+#=> <val bytes32:"0xabababababababababababababababababababababababababababababababab">
+
+a = Timestamp.new               #=> <val timestamp:0>
+
+#  use/change/rename to Timestamp - why? why not?
+#    ALWAYS uses epoch time starting at 0 (no time zone or such)
+
+a = Timedelta.new               #=> <val timedelta:0>
+
+
+#
+#  todo/check:  is bytes a (mutabale)bytebuffer or a frozen/immutable?
+a = Bytes.new                 #=> <val bytes:""> 
+
+
+###########################
+# reference types
+
+
+Array‹String› = Array.new( String )    
+Array‹String›.type      #=> <type string[]>
+
+a = Array‹String›.new   #=> <ref string[]:[]>
+
+a = Array‹String›.new( ['zero', 'one', 'two'] )
+#=>  <ref string[]:
+#       [<val string:"zero">, <val string:"one">, <val string:"two">]>
+a[0]                  #=> <val string:"zero">
+a[1]                  #=> <val string:"one">
+a[2]                  #=> <val string:"two"> 
+a.length              #=> 3
+a.push( 'three' )
+a[3]                  #=> <val string:"three">
+a.push( 'four' )
+a[4]                  #=> <val string:"four">
+a.length              #=> 5
+a.serialize           #=> ["zero", "one", "two", "three", "four"]
+
+
+
+Array‹UInt› = Array.new( UInt )
+Array‹UInt›.type      #=> <type uint[]>
+
+a = Array‹UInt›.new   #=> <ref uint[]:[]>
+
+a = Array‹UInt›.new( [0,1,2] )
+#=> <ref uint[]:
+#      [<val uint:0>, <val uint:1>, <val uint:2>]> 
+a[0]               #=> <val uint:0>
+a[1]               #=> <val uint:1>
+a[2]               #=> <val uint:2>
+a.length           #=> 3
+a.push( 3 )
+a[3]               #=> <val uint:3>
+a.push( 4 )
+a[4]               #=> <val uint:4>
+a.length           #=> 5
+a.serialize        #=> [0, 1, 2, 3, 4]
+
+#  todo/check:  add a "convenience" TypedUIntArray or TypedArray<UInt>
+#                  use special unicode-chars for <>??
+
+
+alice   = '0x'+ 'aa'*20
+bob     = '0x'+ 'bb'*20
+charlie = '0x'+ 'cc'*20
+
+
+Mapping‹Address→UInt›  = Mapping.new( Address, UInt )
+Mapping‹Address→UInt›.type    #=> <type mapping(address=>uint)>
+
+a = Mapping‹Address→UInt›.new
+#=> <ref mapping(address=>uint):{}>
+
+a = Mapping‹Address→UInt›.new( { alice   =>  100,
+                                 bob     =>  200 },
+                             )
+#=> <ref mapping(address=>uint):
+#     {<val address:"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa">=><val uint:100>, 
+#      <val address:"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb">=><val uint:200>}>
+
+a[ alice ]            #=> <val uint:100>
+a[ bob ]              #=> <val uint:200> 
+a[ charlie ]          #=> <val uint:0>
+a[ charlie ] = 300
+a[ charlie ]          #=> <val uint:300>
+
+a.serialize
+#=> {"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"=>100,
+#    "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"=>200,
+#    "0xcccccccccccccccccccccccccccccccccccccccc"=>300}
+
+
+#
+# more - enums, structs, etc.
+
+Color = Enum.new( :Color, :red, :green, :blue )
+Color.type     #=> <type Color enum(red,green,blue)>
+
+Color::RED     #=> <val Color enum(red,green,blue):red(0)>
+Color.red      #=> <val Color enum(red,green,blue):red(0)>
+
+Color::GREEN   #=> <val Color enum(red,green,blue):red(0)>
+Color.green    #=> <val Color enum(red,green,blue):red(0)>
+
+Color.min      #=> <val Color enum(red,green,blue):red(0)>
+Color.max      #=> <val Color enum(red,green,blue):blue(2)>
+
+color = Color.green
+color.serialize   #=> 1 
+
+color = Color.red
+color.serialize   #=> 0
+
+
+
+Bet = Struct.new( :Bet, 
+                     user:    Address,
+                     block:   UInt,
+                     cap:     UInt,
+                     amount:  UInt  )
+Bet.type
+
+
+bet = Bet.new
+bet.user
+bet.amount
+
+bet.user   = Address.new( '0x'+'aa'*20 )
+bet.amount = UInt.new( 123 )
+
+bet.user   = '0x'+'bb'*20    ## literal assign (with typecheck)
+bet.amount = 234             ## literal assign (with typecheck)
+
+bet.serialize
+
+bet = Bet.new( '0x'+'cc'*20,  0, 0, 456, 
+bet.serialize
+
+# ...
+
+end  # module Sandbox
+```
+
+
+And so on.  To be continued ...
+
+
+
+
+
+
+## Bonus - More Blockchain (Crypto) Tools, Libraries & Scripts In Ruby
+
+See [**/blockchain**](https://github.com/rubycocos/blockchain) 
+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.
+Your questions and commetary welcome.
+
+Or post them over at the [Help & Support](https://github.com/geraldb/help) page. Thanks.
+

data/Rakefile

@@ -0,0 +1,27 @@
+require 'hoe'
+require './lib/solidity/typed/version.rb'
+
+
+Hoe.spec 'solidity-typed' do
+  self.version =  Solidity::Module::Typed::VERSION
+
+  self.summary = 'solidity-typed - "zero-dependency" 100%-solidity compatible data type and application binary interface (abi) machinery incl. bool, (frozen) string, address, bytes, uint, int, enum, struct, array, mapping, event, and more for solidity-inspired contract (blockchain) programming languages incl. rubidity et al'
+  self.description = summary
+
+  self.urls    = { home: 'https://github.com/s6ruby/rubidity' }
+
+  self.author  = 'Gerald Bauer'
+  self.email   = 'gerald.bauer@gmail.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = []
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+    required_ruby_version: '>= 2.3'
+  }
+end

data/lib/solidity/typed/array.rb

@@ -0,0 +1,166 @@
+
+
+module Types
+class Array < TypedReference
+    
+    ## todo/check: make "internal" data (array) available? why? why not?
+    ## attr_reader :data   
+
+    def self.zero()  @zero ||= new; end 
+    def zero?()
+      if type.size == 0 ## assume dynamic (starts with empty array)
+        @data.empty?
+      else   ## assume fixed size array (initialized with x zero items) 
+        ## use zero to check - why? why not?
+        ## fix-fix-fix  - add support for fixed Array here or use a new class - why? why not?
+        self == self.class.zero
+      end   
+  end  
+
+
+
+  def initialize( initial_value = [] )
+      ## was: initial_value ||= []
+      ##     check if nil gets passed in - default not used?  
+      raise ArgumentError, "expected literal of type #{type}; got typed #{initial_value.pretty_print_inspect}"    if initial_value.is_a?( Typed )    
+ 
+     @data =  type.check_and_normalize_literal( initial_value ).map do |item|
+                    type.sub_type.new( item )
+              end 
+
+      ## check size if fixed (must all set to zero up to size!!!)         
+      if type.size > 0  ## auto-init with zeros
+         if @data.size >= type.size  ## note: allow ("fixed") array to grow bigger for now - why? why not?
+            # bingo! already setup with inital values
+         else
+            self.size = type.size
+         end
+      end     
+  end
+
+
+
+  extend Forwardable   ## pulls in def_delegator
+  ## add more Array forwards here!!!!
+  ##  todo/fix:  wrap size, empty?  return value literals into typed values - why? why not?
+  def_delegators :@data, :size, :length,
+                         :empty?,
+                         :each, :each_with_index
+                         
+
+  def []( index )
+    ## use serialize to get value (why not value) - why? why not?
+    index = index.is_a?( Typed ) ? index.as_data : index
+  
+    ## fix: use index out of bounds error - why? why not?
+    raise ArgumentError, "Index out of bounds -  #{index} : #{index.class.name} >= #{@data.size}"   if index >= @data.size
+
+    obj = @data[ index ] 
+    if obj.nil?  
+      obj = type.sub_type.new_zero
+      @data[ index ] = obj
+    end
+    obj
+  end
+ 
+  def []=(index, new_value) 
+     ## use serialize to get value (why not value) - why? why not?
+     index = index.is_a?( Typed ) ? index.as_data : index
+ 
+     raise ArgumentError, "Sparse arrays are not supported; index out of bounds - sorry"   if index >= @data.size
+
+     # fix-fix-fix: allow typed value here (not only literals)!!!
+     obj = if new_value.is_a?( Typed ) 
+               new_value
+           else
+               type.sub_type.new( new_value )
+           end
+  
+     @data[ index ] = obj
+  end
+  
+
+  def pop
+     ## note: pop will decrease size/lenght!!!
+     ## will remove LAST item in array!!!
+     ##
+     ## Pop is used to delete or remove an element 
+     ##   in a dynamic array from the end.
+     @data.pop
+  end
+
+  def push( new_value )
+     ## note: push will increase size/length!!!
+     ##
+     ## Push is used to add new element to a dynamic array,
+     ##  when you push a value to an array, it becomes the last value
+     obj = if new_value.is_a?( Typed ) 
+               new_value
+           else
+               type.sub_type.new( new_value )
+           end
+     @data.push( obj )
+
+     ## note: returns array.size (NOT array itself!!!) to keep compatible with solidity - why? why not?
+     @data.size
+  end
+
+
+  def delete( index )
+    ## note sets the element to zero!!!
+    ##  will NOT remove from array itself!!!
+  
+    ## use serialize to get value (why not value) - why? why not?
+    index = index.is_a?( Typed ) ? index.as_data : index
+  
+    ## fix: use index out of bounds error - why? why not?
+    raise ArgumentError, "Index out of bounds -  #{index} : #{index.class.name} >= #{@data.size}"   if index >= @data.size
+
+    @data[ index ] = type.sub_type.new_zero
+    self
+  end
+
+
+  def size=( new_size )
+    ## todo/check: value must be greater 0 and greater than current size
+    diff = new_size - @data.size
+    if diff == 0
+      ## stay as is; do nothing
+    elsif diff > 0
+      ## todo/check:
+      ##    always return (deep) frozen zero object - why? why not?
+      ##     let user change the returned zero object - why? why not?
+      if type.sub_type.respond_to?( :new_zero )
+        ## note: use a new unfrozen copy of the zero object
+        ##    changes to the object MUST be possible (new "empty" modifable object expected)
+        diff.times { @data << type.sub_type.new_zero }
+      else
+         raise "[Array]#length= cannot create new_zero for type #{type.sub_type} - sorry"
+      end
+    else  ## diff < 0
+      ## fix-fix-fix - raise error here - cannot shrink/delete via length!!!
+    end
+    self  # return reference to self
+  end
+  alias_method :length=, :size=   ## always use length (and remove size?) - why? why not?
+
+
+  def clear
+    ## note: reset ary to zero  (NOT empty e.g. [])
+    ##         differes for "fixed" size arrays
+    @data.clear
+    self.size = type.size   if type.size > 0  ## auto-init with zeros
+    self  # return reference to self
+  end
+
+
+  def as_data
+     @data.map {|item| item.as_data } 
+  end
+
+  def pretty_print( printer ) 
+    printer.text( "<ref #{type}:#{@data.pretty_print_inspect}>" ); 
+  end
+end  # class Array
+end  # module Types
+

data/lib/solidity/typed/array_builder.rb

@@ -0,0 +1,53 @@
+
+module Types
+class Array
+
+## note: add size option here (size=0) default is dynamic (not fixed)!!!  
+def self.build_class( sub_type, size=0 )
+  ## add convenience sub_type helper here - why? why not?
+  ## sub_type = Type.create( sub_type )  if sub_type.is_a?( Symbol ) ||
+  ##                                       sub_type.is_a?( String )
+  ## sub_type = sub_type.type   if sub_type.is_a?( Class ) && sub_type.ancestors.include?( Typed )
+   sub_type = typeof( sub_type )    
+  
+  type = ArrayType.instance( sub_type, size )
+
+  class_name =  type.typedclass_name
+  
+    ## note: keep a class cache
+    ##  note: klasses may have different init sizes (default 0)
+    cache           = @@cache ||= {}
+    klass           = cache[ class_name ]
+    ## fix-fix-fix - check if const klass defined for cache (no cache needed)!!!!!!!!
+  
+    if klass.nil?
+      klass = Class.new( Array )
+      klass.define_singleton_method( :type ) do
+        @type  ||= type
+      end
+
+      ## add self.new too - note: call/forward to "old" orginal self.new of Event (base) class
+      klass.define_singleton_method( :new ) do |*args|
+         old_new( *args )
+      end
+    
+      ## add to cache for later (re)use
+      cache[ class_name ] = klass
+
+      ## for default scope use Kernel - why? why not?
+      ##   or Globals  or Typed - why? why not?
+      Types.const_set( class_name, klass )
+    end
+
+    klass
+end   # method self.build_class 
+
+class << self
+  alias_method :old_new, :new       # note: store "old" orginal version of new
+  alias_method :new,     :build_class    # replace original version with create
+end
+
+
+end   # class Array
+end  # module Types
+

data/lib/solidity/typed/bool.rb

@@ -0,0 +1,47 @@
+#########
+### monkey patch built-in FalseClass & TrueClass
+##   move to core-ext directory or such - why? why not?
+
+
+## note. Bool is a module (NOT a class)
+##         adding a new superclass in ruby NOT possible
+##                still waiting for common base clase for bools in ruby!!!
+##   see  https://github.com/geraldb/talks/blob/master/bool.md
+##    or  https://github.com/rubycocos/core/tree/master/safebool 
+
+
+module Bool
+  def type()     self.class.type; end
+  def as_data()  self;  end  ## that is, return true or false
+ 
+  ## note:
+  ##  self.type or such WILL not get included  
+  ##   via module include in TrueClass & FalseClass
+  ##   add in TrueClass & FalseClass
+  ##   TrueClass.type will NOT work via "inheritance" like a "true" superclass - why? why not?
+  def self.type() Types::Typed::BoolType.instance; end 
+  ## note: lets you use Bool.type
+  def self.zero() false; end
+end  # module Bool
+
+
+
+
+class FalseClass
+    include Bool     ## "hack" - enables false.is_a?(Bool)
+                     ##             and false.type 
+                     ##             and false.as_data
+  
+    def self.type()  Types::Typed::BoolType.instance; end
+    def zero?() true; end
+end
+
+class TrueClass
+    include Bool    ## "hack" - enables true.is_a?(Bool)
+                    ##             and true.type 
+                    ##             and true.as_data
+
+    def self.type()  Types::Typed::BoolType.instance; end
+    def zero?() false; end
+end
+