JarCasting
Java API for Zold. Ruby API is in zold-io/zold.
All you need is this:
<dependency>
<groupId>io.zold</groupId>
<artifactId>java-api</artifactId>
<version><!-- Get it here: https://github.com/zold-io/java-api/releases --></version>
</dependency>
Java version required: 1.8+.
We recommend you read the Zold whitepaper in order to understand the concepts behind this API.
First, you find a wallet in a directory of wallets:
final Wallets wallets = new WalletsIn(new File("/tmp/wallets"));
final Wallet wallet = new Filtered<>(
w -> "9999888877776666".equals(w.id()),
wallets
).iterator().next();
Then, you pull the network's version of the wallet and merge it into yours:
final Wallet merged = wallet.merge(
network.pull(wallet.id())
);
Then, you make a payment:
final long amount = 1999L; //zents
final char bnf = (char) 12345; //beneficiary wallet's ID
wallet.pay(amount, bnf);
Finally, you push it:
network.push(wallet);
That's it.
How to contribute?
Just fork the repo and send us a pull request.
Make sure your branch builds without any warnings/issues:
mvn clean install -Pqulice
License (MIT)
Copyright (c) 2018 Yegor Bugayenko
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Requirements
These are the requirements for this API.
Note: The original whitepaper on zold can be found here. The whitepaper and the documentation found at www.zold.io serve as the highest authority on the subject of zold. The following requirements are condensed versions of the points expressed in the aforementioned docs as they relate to the scope of this project:
- Maintain a wallet in structured textual format, within which is a ledger that contains transactions for that wallet.
- Make payments:
- Taxes according to fixed formula
- Payments to other wallets
- Sign with RSA key
- Push to network
- Receive payments:
- Pull the paying wallet from the network
- Merge the copies of the paying wallet with our own copy
- We need to refresh our local database of network nodes by querying the network.
- We must implement with Java 8
- Non-functional requirements were not made, but we expect
- Flawless concurrency
- "Decent" performance
- Design must respect the principles of elegant objects
- Design must resemble the design of the original ruby API
Decisions and Alternatives
javax-jsonis a Java API that can parse and also write JSON. As part of the EE7 spec, it is stable, well established, and is the standard. We can use it to write to our local database file. Alternatives are google's gson, JSON-java, jackson-databind, and many others.- The standard
java.securitypackage contains everything we need to import keystores and sign/encrypt messages with RSA keys. There are lots of examples on the internet on how to use it. I am not aware of any other popular alternative out there. cactoos-httpis a new object-oriented HTTP API under current development as part of projectcactoosin Zerocracy. It is expected to be ready by the time this API goes to production. Other alternatives are Apache's http client (not object-oriented),jcabi-http(too many dependencies), and many others.- Our API will consist of our core classes that will communicate with the network using cactoos-http + javax.json, a local storage (
nodes.json) for persistence of remote node data, will use thejava.securitypackage when signing the transactions, and will expect wallet files to have the.zextension (discuss) and conform to the format specified in the whitepaper:
Concerns
cactoos-httpis designed according to the principles of EO, although it still has mayor hurdles to overcome (eg. see #62).javax.jsonwill parse data from the zold network and write our local database file in structured JSON format. Its usage is very simple, although we will probably have to be careful with regards to concurrent access to the file.java.securityruntimes can handle RSA and MD5 on all platforms.
Assumptions
cactoos-httpwill reach the maturity level necessary to support our requirements- We can flawlessly manage synchronized access to our local database file
Risks
- The
cactoos-httpproject might not obtain the resources to reach maturity, or may not reach maturity for some other reason. - Our bottleneck will be reading/writing our local database file. We might not be able to manage a "heavy" throughput.
