Universal Credit Contractor

Smart Contracts
1

THE UNIVERSAL CREDIT CONTRACTOR

This thread is about the Universal Credit Contractor. The contractor acts as a wrapper script for the ucs_client.sh script and allows the user to set up smart contracts for transactions. When executed the bash script ucs_contractor.sh will source the logic and perform actions based on the logic and the ruleset.

WHAT IS A CONTRACT?

A contract always consists of at least two files:

  • a file that contains the actual logic in the folder /contracts/ (that contains a definition of a function called contract_action() which is sourced)
  • a file that contains the ruleset in the folder /rulesets/ (definitions of variables used by the logic)

Both files are handed over to ucs_contractor.sh via parameters. At execution, the logic of the contract is loaded and controlled with the variables of the rulesets file. In principle, any logic can be implemented.

HOW TO SETUP

STEP 1 : GET THE SOURCES

To run the contractor you need to have a full client set up with a user. See GitHub Readme how to install and run the client. Assuming you already have the client, step into ths directory and unpack the contractor:

tar -xvf contractor.tar

The tarball contains the following files/folders:

  • the script ucs_contractor.sh
  • the folder /contracts/
  • the folder /rulesets/
  • the file /control/contractor_HELP.txt

The tarball also contains some example contracts (cashier, filter, accountant and tombola) and related rulesets for these contracts.

STEP 2 : DEFINE YOUR CONTRACT(S)

Create a smart contract logic and a ruleset based on your needs.

EXAMPLE

The following example is a ruleset for the supplied smart contract accountant.logic. The smart contract accountant.logic acts as a simple accountant sending transactions based on received transactions. Only parameters related to the transaction can be defined as triggers and the action is limited to the creation of new transaction (s).

See below example ruleset accountant.ruleset:

ruleset_asset="YOUR_ASSET_HERE"
ruleset_sender="*"
ruleset_receiver="YOUR_ADRESS_HERE"
ruleset_amount="*"
ruleset_amount_comparison_operator=""
ruleset_amount_comparison_variable=""
ruleset_purpose="*"
ruleset_required_confirmations=0
contract_asset="${trx_asset}"
contract_sender="YOUR_ADRESS_HERE"
contract_sender_password="YOUR_PASSWORD_HERE"
contract_receiver="${trx_sender}"
contract_amount="${trx_amount}"
contract_purpose=`echo "${trx_file}"|sha256sum|cut -d ' ' -f1`
contract_type="partial"
alias send_trx='${script_path}/ucs_client.sh -action create_trx -sender ${contract_sender} -password "${contract_sender_password}" -receiver ${receiver} -amount ${contract_amount} -asset ${contract_:asset} -purpose ${contract_purpose} -type ${contract_type}'

The above ruleset ensures that the smart contract accountant.logic sends all transactions that were sent to you back to the sender (if you enter your address and password).

accountant.logic will look for transactions:

  • matching the defined asset(ruleset_asset="YOUR_ASSET_HERE" )
  • having any sender (ruleset_sender="*" )
  • you as receiver (ruleset_receiver="PUT_YOUR_ADRESS_HERE" )
  • any amount (ruleset_amount="*" )
  • any purpose (ruleset_purpose="*" )
  • with no confirmations (ruleset_required_confirmations=0 )

If one or multiple transactions match this criteria the contractor will create a transaction:

  • having the initial asset that was sent as asset to send (contract_asset="${trx_asset}" )
  • having the initial amount that was sent as amount to send (contract_amount="${trx_amount}" )
  • the initial sender as receiver(contract_receiver="${trx_sender}" )
  • with a sha256 hash of the initial trx filename as purpose (contract_purpose=echo "${trx_file}"|sha256sum|cut -d ' ' -f1 )
  • the transaction type is ‘partial’.

And finally the alias named “send_trx” is defined. That is actually the action that is being triggered.

STEP 3 : SCHEDULE THE CONTRACTOR

You either manually execute the ucs_contractor.sh or schedule a job for this e.g. with CRON. To execute your contract simply handover your ruleset and your contract with full path:

./ucs_contractor.sh -ruleset /path/to/contract.ruleset -contract /path/to/contract.logic

Please note that accountant.logic will create no output If no transaction matched the ruleset.

To display the help text run:

./ucs_contractor.sh -help

More information:
At execution the ucs_contractor.sh script will check if a contract file is there (parameter -contract <PATH>) and if a ruleset file is there (parameter -ruleset <PATH>). If both files are there the function contract_action() of the contract logic file will be sourced and called. That’s all.

This means that if you need a ruleset file the logic to source/read it must be placed within the contract logic (see accountant.logic and tombola.logic) So the ruleset file is NOT sourced within ucs_contractor.sh. The contractor only sources the logic file and calls the function within that file. This logic file can contain whatever you want. All triggers and actions must be defined in a function named contract_action().

Depending on what you want to do you might not need a ruleset file, but the ucs_contractor.sh will still check if that file is there. A solution would be to handover the same path for -ruleset as for -contract.

The fact that contract logic and ruleset are separate files allows the user to run the same contract logic with different rulesets!