Skip to content

Latest commit

 

History

History
384 lines (277 loc) · 14 KB

README.md

File metadata and controls

384 lines (277 loc) · 14 KB
Raw

Glueby Ruby Gem Version MIT License

Glueby is a smart contract library on the Tapyrus blockchain. This is designed as you can use without any deep blockchain understanding.

Features

Glueby has below features.

  1. Wallet You can manage wallets for application users. This wallet feature is a foundation of Contracts below to specify tx sender and so on.
    You can choose two sorts of wallet implementation :activerecord and :core. :activerecord is implemented using ActiveRecord on RDB. :core uses the wallet that bundled with Tapyrus Core.

  2. Contracts
    You can use some smart contracts easily

    • Timestamp: Record any data as a timestamp to a tapyrus blockchain.
    • Payment: Transfer TPC.
    • Token: Issue, transfer and burn colored coin.

  3. Sync blocks with your application
    You can use BlockSyncer when you need to synchronize the state of an application with the state of a blockchain.
    See more details at BlockSyncer.

  4. Take over tx sender's fees
    FeeProvider module can bear payments of sender's fees. You should provide funds for fees to FeeProvider before use.
    See how to set up at Use fee provider mode

Installation

Add this line to your application's Gemfile:

gem 'glueby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install glueby

Setup for Ruby on Rails application development

  1. Add this line to your application's Gemfile

    gem 'glueby'

    and then execute

     $ bundle install

  2. Run installation rake task

     $ rails glueby:contract:install

  3. Run Tapyrus Core as dev mode

    We recommend to run as a Docker container. Docker image is here.

    Starts tapryusd container

     $ docker run -d --name 'tapyrus_node_dev' -p 12381:12381 -e GENESIS_BLOCK_WITH_SIG='0100000000000000000000000000000000000000000000000000000000000000000000002b5331139c6bc8646bb4e5737c51378133f70b9712b75548cb3c05f9188670e7440d295e7300c5640730c4634402a3e66fb5d921f76b48d8972a484cc0361e66ef74f45e012103af80b90d25145da28c583359beb47b21796b2fe1a23c1511e443e7a64dfdb27d40e05f064662d6b9acf65ae416379d82e11a9b78cdeb3a316d1057cd2780e3727f70a61f901d10acbe349cd11e04aa6b4351e782c44670aefbe138e99a5ce75ace01010000000100000000000000000000000000000000000000000000000000000000000000000000000000ffffffff0100f2052a010000001976a91445d405b9ed450fec89044f9b7a99a4ef6fe2cd3f88ac00000000' tapyrus/tapyrusd:edge

  4. Modify the glueby configuration

    # Use tapyrus dev network
Tapyrus.chain_params = :dev
Glueby.configure do |config|
  config.wallet_adapter = :activerecord
  # Modify rpc connection info in config/initializers/glueby.rb that is created in step 3.
  config.rpc_config = { schema: 'http', host: '127.0.0.1', port: 12381, user: 'rpcuser', password: 'rpcpassword' }
end

  5. Generate db migration files for wallet feature

    These are essential if you use config.wallet_adapter = :activerecord configuration.

     $ rails g glueby:contract:block_syncer
 $ rails g glueby:contract:wallet_adapter

    If you want to use reissuable token or timestamp, you need to do below generators.

     $ rails g glueby:contract:reissuable_token
 $ rails g glueby:contract:timestamp

    Then, run the migrations.

     $ rails db:migrate

Provide initial TPC (Tapyrus Coin) to wallets

To use contracts, wallets need to have TPC and it can be provided from coinbase tx.

  1. Create a wallet and get receive address

    wallet = Glueby::Wallet.create
wallet.balances # => {}
address = wallet.internal_wallet.receive_address
puts address

  2. Generate a block

    Set an address you got in previous step to [Your address]

     $ docker exec tapyrus_node_dev tapyrus-cli -conf=/etc/tapyrus/tapyrus.conf generatetoaddress 1 "[Your address]" "cUJN5RVzYWFoeY8rUztd47jzXCu1p57Ay8V7pqCzsBD3PEXN7Dd4"

  3. Sync blocks if you use :activerecord wallet adapter

    You don't need to do this if you are using :core wallet_adapter.

     $ rails glueby:contract:block_syncer:start

    Here the wallet created in step 1 have 50 TPC and you can see like this:

    wallet.balances # =>  {""=>5000000000}

    TPC amount is shown as tapyrus unit. 1 TPC = 100000000 tapyrus.

Timestamp

Glurby.configure do |config|
  config.wallet_adapter = :activerecord
  config.rpc_config = { schema: 'http', host: '127.0.0.1', port: 12381, user: 'user', password: 'pass' }
end

wallet = Glueby::Wallet.create
timestamp = Glueby::Contract::Timestamp.new(wallet: wallet, content: "\x01\x02\x03")
timestamp.save!
# "a01eace94ce6cdc30f389609de8a7584a4e208ee82fec33a2f5875b7cee47097"

We can see the timestamp transaction using getrawblockchain command

> tapyrus-cli -rpcport=12381 -rpcuser=user -rpcpassword=pass getrawtransaction a01eace94ce6cdc30f389609de8a7584a4e208ee82fec33a2f5875b7cee47097 1

{
  "txid": "a01eace94ce6cdc30f389609de8a7584a4e208ee82fec33a2f5875b7cee47097",
  "hash": "a559a84d94cff58619bb735862eb93ff7a3b8fe122a8f2f4c10b7814fb15459a",
  "features": 1,
  "size": 234,
  "vsize": 234,
  "weight": 936,
  "locktime": 0,
  "vin": [
    {
      "txid": "12658e0289da70d43ae3777a174ac8c40f89cbe6564ed6606f197764b3556200",
      "vout": 0,
      "scriptSig": {
        "asm": "3044022067285c57a57fc0d7f64576abbec65639b0f4a8c31b5605eefe881edccb97c62402201ddec93c0c9bf3bb5707757e97e7fa6566c0183b41537e4f9ec46dcfe401864d[ALL] 03b8ad9e3271a20d5eb2b622e455fcffa5c9c90e38b192772b2e1b58f6b442e78d",
        "hex": "473044022067285c57a57fc0d7f64576abbec65639b0f4a8c31b5605eefe881edccb97c62402201ddec93c0c9bf3bb5707757e97e7fa6566c0183b41537e4f9ec46dcfe401864d012103b8ad9e3271a20d5eb2b622e455fcffa5c9c90e38b192772b2e1b58f6b442e78d"
      },
      "sequence": 4294967295
    }
  ],
  "vout": [
    {
      "value": 0.00000000,
      "n": 0,
      "scriptPubKey": {
        "asm": "OP_RETURN 039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81",
        "hex": "6a20039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81",
        "type": "nulldata"
      }
    },
    {
      "value": 49.99990000,
      "n": 1,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 3c0422f624f2503193c7413eff32839b9e151b54 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a9143c0422f624f2503193c7413eff32839b9e151b5488ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "16ULVva73ZhQiZu9o3njXc3TZ3aSog7FQQ"
        ]
      }
    }
  ],
  "hex": "0100000001006255b36477196f60d64e56e6cb890fc4c84a177a77e33ad470da89028e6512000000006a473044022067285c57a57fc0d7f64576abbec65639b0f4a8c31b5605eefe881edccb97c62402201ddec93c0c9bf3bb5707757e97e7fa6566c0183b41537e4f9ec46dcfe401864d012103b8ad9e3271a20d5eb2b622e455fcffa5c9c90e38b192772b2e1b58f6b442e78dffffffff020000000000000000226a20039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81f0ca052a010000001976a9143c0422f624f2503193c7413eff32839b9e151b5488ac00000000",
  "blockhash": "d33efc626114f89445d12c27f453c209382a3cb49de132bf978449093f2d2dbb",
  "confirmations": 3,
  "time": 1590822803,
  "blocktime": 1590822803
}

Rails support

Glueby supports ruby on rails integration.

To use in rails, Add dependency to Gemfile.

Then invoke install task.

bin/rails glueby:contract:install

Install task creates a file glueby.rb in config/initializers directory like this.

# Edit configuration for connection to tapyrus core
Glueby.configure do |config|
  config.wallet_adapter = :activerecord
  config.rpc_config = { schema: 'http', host: '127.0.0.1', port: 12381, user: 'user', password: 'pass' }
end

If you use timestamp feature, use glueby:contract:timestamp generator.

bin/rails g glueby:contract:timestamp
    create  db/migrate/20200613065511_create_timestamp.rb
bin/rails db:migrate
== 20200613065511 CreateTimestamp: migrating ==================================
-- create_table(:timestamps)
   -> 0.0023s
== 20200613065511 CreateTimestamp: migrated (0.0024s) =========================

Now, Glueby::Contract::AR::Timestamp model is available

irb(main):001:0> wallet = Glueby::Wallet.create
=> #<Glueby::Wallet:0x00007fe8333f7d98 @internal_wallet=#<Glueby::Internal::Wallet:0x00007fe8333f7dc0 @id="70a58204a7f4cb10d973b762f17fdb4b">>
irb(main):003:0> t = Glueby::Contract::AR::Timestamp.new(wallet_id: wallet.id, content:"\x01010101", prefix: "app")
   (0.5ms)  SELECT sqlite_version(*)
=> #<Glueby::Contract::AR::Timestamp id: nil, txid: nil, status: "init", content_hash: "9ccc644b03a88358a754962903a659a2d338767ee61674dde5...", prefix: "app", wallet_id: "70a58204a7f4cb10d973b762f17fdb4b">
irb(main):004:0> t.save
   (0.1ms)  begin transaction
  Glueby::Contract::AR::Timestamp Create (0.4ms)  INSERT INTO "timestamps" ("status", "content_hash", "prefix", "wallet_id") VALUES (?, ?, ?, ?)  [["status", 0], ["content_hash", "9ccc644b03a88358a754962903a659a2d338767ee61674dde5434702a6256e6d"], ["prefix", "app"], ["wallet_id", "70a58204a7f4cb10d973b762f17fdb4b"]]
   (2.1ms)  commit transaction
=> true

After create timestamp model, run glueby:contract:timestamp:create task to broadcast the transaction to the Tapyrus Core Network and update status(init -> unconfirmed).

bin/rails glueby:contract:timestamp:create
broadcasted (id=1, txid=8d602ca8ebdd50fa70b5ee6bc6351965b614d0a4843adacf9f43fedd7112fbf4)

Run glueby:block_syncer:start task to confirm the transaction and update status(unconfirmed -> confirmded).

bin/rails glueby:block_syncer:start

Use fee provider mode

Glueby contracts have two different way of fee provisions.

  1. :sender_pays_itself
  2. :fee_provider_bears

The first one: :sender_pays_itself, is the default behavior. In the second Fee Provider mode, the Fee Provider module pays a fee instead of the transaction's sender.

Fee Provider Specification

  • Fee Provider pays fixed amount fee, and it is configurable.
  • Fee Provider needs to have enough funds into their wallet.
  • Fee Provider is managed to keep some number of UTXOs that have fixed fee value by rake tasks.

Setting up Fee Provider

  1. Set like below
Glueby.configure do |config|
  # Use FeeProvider to supply inputs for fees on each transaction that is created on Glueby.
  config.fee_provider_bears!
  config.fee_provider_config = {
    # The fee that Fee Provider pays on each transaction.
    fixed_fee: 1000,
    # Fee Provider tries to keep the number of utxo in utxo pool as this size using `glueby:fee_provider:manage_utxo_pool` rake task
    utxo_pool_size: 20 
  }
end
  1. Deposit TPC into Fee Provider's wallet

Get an address from the wallet.

$ bundle exec rake glueby:fee_provider:address
mqYTLdLCUCCZkTkcpbVx1GqpvV1gK4euRD

Send TPC to the address.

If you use Glueby::Contract::Payment to the sending, you can do like this:

Glueby::Contract::Payment.transfer(sender: sender, receiver_address: 'mqYTLdLCUCCZkTkcpbVx1GqpvV1gK4euRD', amount: 1_000_000)
  1. Manage UTXO pool

The Fee Provider's wallet has to keep some UTXOs with fixed_fee amount for paying fees using manage_utxo_pool rake task below. This rake task tries to split UTOXs up to utxo_pool_size. If the pool has more than utxo_pool_size UTXOs, it does nothing.

$ bundle exec rake glueby:fee_provider:manage_utxo_pool
Status: Ready
TPC amount: 999_000
UTXO pool size: 20

Configuration:
  fixed_fee = 1_000
  utxo_pool_size = 20

This shows that the UTXO pool has 20 UTXOs with fixed_fee amount for paying fees and has other UTXOs that never use for paying fees. The sum of all the UTXOs that includes both kinds of UTXO is 999_000 tapyrus.

If the wallet doesn't have enough amount, the rake task shows an error like:

$ bundle exec rake glueby:fee_provider:manage_utxo_pool
Status: Insufficient Amount
TPC amount: 15_000
UTXO pool size: 15

1. Please replenishment TPC which is for paying fee to FeeProvider. 
   FeeProvider needs 21000 tapyrus at least for paying 20 transaction fees. 
   FeeProvider wallet's address is '1DBgMCNBdjQ1Ntz1vpwx2HMYJmc9kw88iT'
2. Then create UTXOs for paying in UTXO pool with 'rake glueby:fee_provider:manage_utxo_pool'

Configuration:
  fixed_fee = 1_000
  utxo_pool_size = 20

If you want to get the status information, you can use the status task.

$ bundle exec rake glueby:fee_provider:status
Status: Ready
TPC amount: 999_000
UTXO pool size: 20

Configuration:
  fixed_fee = 1_000
  utxo_pool_size = 20

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/glueby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Glueby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.