CoinRelay: crypto-currency payment response scripting language.
What does the above mouthful mean?
CoinRelay is a scripting language and client especially designed to listen to incoming payments or events on the blockchain and programmatically generate new responses to those payments.
Possible uses include:
- Splitting payments by percentage for multiple parties, or personal budgeting
- Splitting payments into fixed upfront costs and profits
- Generate a payment address that forwards multiple payment addresses to one central address (for order-tracking, for example)
- Blockchain-based gambling games
- Inheritance contracts and dead-man's switches
- Investment plans involving timed conversion to fiat
- And many more!
If you use or like this project please consider donating: 1RELAY11yrKkqxpCSwE7moim2s38a4nJN
CoinRelay scripts are a sequence of commands that are executed in response to a payment to an address. For examples, see the examples directory.
One example of a simple "Hello World" script would be a script that automatically relays payments to a single forwarding address.
$balance minus_fee #push the balance of the host address on the stack. Subtract the default fee
send<1C6wmFUj6HF9aqRZucWEMa7xuTr6Z8sQj3> #Add a send of the amount on the stack to the current transaction
$default_fee pushtx #push the default fee on the stack. Send the current transaction on the network
For more information and a tutorial on the programming model and grammar, see doc/language.md. In order to see full documentation on all supported instructions, see doc/instructions.md, which is autogenerated from the source code documentation by running
$ python coinrelay.py > doc/instructions.md
In order to run a coinrelay script, one uses the coinrelay client to associate a script with an address. Then the client listens to the blockchain for payments to that address, then runs the associated script if a payment is recieved.
The language is designed to be 1) simple to use 2) expressive and flexible 3) Sandboxed. Expounding on point 3), this means that it is in theory possible to safely host nodes that run coinrelay scripts on behalf of other anonymous users (possibly for a fee) without fear of losing funds or being dossed. To this end the language is designed to not be turing complete in order to prevent user-uploaded scripts from taking over the CPU time of a node.
####Get the dependencies
The CoinRelay reference implementation here needs
- Python
- OpenSSL
- Other Stuff???
- An active internet connection (for the blockchain)
####Compiling/Testing an example
This implementation of coinrelay includes a development tool 'testing' mode which allows you to compile and execute coinrelay source in a simulated blockchain and a test transaction and address so no finances are involved. All commands that push transactions to the blockchain are simulated instead. This testing mode also displays the intermediate "assembly" (python) that the coinrelay compiler produces, as well as the trace of the underlying stack machine as the code runs for debugging. To use it on an example, run.
$ python crcc.py test example/simple_relay.crs
This process is recommended to develop/test your own scripts prior to deployment as well.
Side note, the coolest example is probably SatoshiDice 48% in 15 lines
####Running a script on the real blockchain
This implementation allows you to run your scripts on the real blockchain. To do this, you need to 1) register your script to an address in the listener database in the local directory. 2) run the crcc client as a daemon to listen to the blockchain in the local directory.
######Registering a script to an address
To register a script to a new address, run
$ mkdir localdb
$ cd localdb
$ python /path/to/crcc.py update path/to/script.crs
The generated address will be printed to standard out and the private key will be saved to the database (in plaintext (!), so be sure you either use throwaway addresses or trust the node operator)
Alternately, you may provide a private key as a second argument to register a specific address to the script (for vanity addresses)
$ python crcc.py update path/to/script.crs 5KPvPhq2i912WMaXyWtCSj55Fk8nuqHYAmA66tVMpbycLNNhb6z
If you are running the listener daemon at the same time in another process, you CAN update the script associated with the address in parallel. Or you may update the script before the listener is running.
######Running the listener daemon
To run the listener daemon,
$ cd localdb
$ python /path/to/crcc.py listen
WARNING: Due to a bug in the listener daemon, the daemon cannot be stopped with Ctrl-C. This bug is being fixed.
If you use or like this project please consider donating to me the developer: 1RELAY11yrKkqxpCSwE7moim2s38a4nJN