Add README.md and LICENSE.md

LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2023` `nitowa`
+
+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
+NONINFRINGEMENT. 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.

README.md

@@ -1 +1,138 @@
-## The home of RJSVM, the Ripple JavaScript Virtual Machine
+# Overview 
+
+[![Current Version](https://img.shields.io/npm/v/rjsvm.svg)](https://www.npmjs.com/package/rjsvm)
+[![Weekly Downloads](https://img.shields.io/npm/dw/rjsvm?color=important)](https://www.npmjs.com/package/rjsvm)
+[![License Type](https://img.shields.io/npm/l/rjsvm?color=blueviolet)](https://gitea.nitowa.xyz/docs/rjsvm/src/branch/master/LICENSE.md)
+
+The Ripple JavaScript Virtual Machine, or RJSVM, aims to standardize and simplify the development of applications that employ the Ripple blockchain as state storage. Internally it employs [xrpIO](https://gitea.nitowa.xyz/npm-packages/xrpio) to read and write all necessary data.
+
+# How to install
+```
+npm i rjsvm
+```
+
+# How it works
+
+The JSVM package comes with two major parts: The RJSVM itself and the Datawriter. The former is used to define initial program state, callable endpoints, and the associated their associated logic. The Datawriter serves as the glue between users and a RJSVM. 
+
+Due to the blockchain's properties of providing persistent and absolutely ordered transactions every copy of a RJSVM will behave exactly identically.
+
+![rjsvm schema](https://imgur.com/Wpqp4yX.jpg)
+
+In order to provide a more robust environment and quasi-typesafe execution this package also requires [zod](https://www.npmjs.com/package/zod).
+
+# A basic example
+
+RJSVM
+```typescript
+import { RJSVM_Builder, RJSVM_Implementations, RJSVM_Interface, RJSVM, RJSVM_Config } from "rjsvm";
+import { z } from "zod";
+
+// Begin by defining the parameter type using Zod
+const blogpostSchema = z.object({
+    title: z.string(),
+    body: z.string(),
+    from: z.string(),
+})
+type Blogpost = z.infer<typeof blogpostSchema>
+
+// Define the shape of the state the RJSVM will manipulate
+type State = {
+    data: Blogpost[]
+}
+
+// Define the RJSVM endpoints
+type RJSVMEndpoints = {
+    submit: (data: Blogpost) => void
+    ownerSubmit: (data: Blogpost) => void
+    remove: (data: Blogpost) => void
+}
+
+// Define initial RJSVM state. The 'owner' and 'state' fields are both required.
+abstract class RJSVM_Base
+extends RJSVM<State, RJSVMEndpoints>
+implements RJSVM_Interface<RJSVM_Base> {
+    owner = ownerWallet.address
+
+    state: State = {
+        blogposts: []
+    }
+}
+
+// Implement the program logic
+const RJSVM_Contract: RJSVM_Implementations<RJSVM_Base> = {
+    // Endpoints may declare a minimum fee in order to be applied
+    submit: {
+        implementation: function (env, data) {
+            this.state.blogposts.unshift(data)
+        },
+        visibility: 'public',
+        fee: 10,
+        parameterSchema: blogpostSchema
+    },
+
+    // Endpoints can be owner-exclusive in order to grant free access
+    ownerSubmit: {
+        implementation: function (env, shout) {
+            this.state.blogposts.unshift(shout)
+        },
+        visibility: 'owner',
+        parameterSchema: blogpostSchema
+    },
+
+    // Owner-exclusive endpoints can also be used to implement protected functionality
+    remove: {
+        implementation: function (env, data) {
+            this.state.blogposts = this.state.blogposts.filter(post => post.title != post.title)
+        },
+        visibility: 'owner',
+        parameterSchema: blogpostSchema,
+    }
+}
+
+// Finally build and connect the RJSVM
+const Rjsvm = RJSVM_Builder.from(RJSVM_Base, RJSVM_Contract);
+
+const conf: RJSVM_Config = {
+    listeningAddress: listeningWallet.address,          // The XRP address to check for endpoint calls
+    rippleNode: "wss://s.altnet.rippletest.net:51233"   // Any online XRP node connected to the right chain
+}
+
+const rjsvm = new Rjsvm(conf)
+rjsvm.connect()
+```
+
+Datawriter
+```typescript
+import { Datawriter } from "rjsvm";
+
+const datawriter = new Datawriter({
+    sendWallet: userWallet,                     // A wallet controlled by the user
+    receiveAddress: drainWallet.address,        // A secondary address controlled by the user
+    xrpNode: xrpNode,                           // Any online XRP node connected to the right chain
+    contractAddress: listeningWallet.address    // The XRP associated with the RJSVM
+})
+
+datawriter.callEndpoint('submit', { 
+    title: "My first blogpost", 
+    body: "Hello hello this is a blogpost!", 
+    from: "#1 RJSVM User in the world" 
+}, 10)
+// once the ripple blockchain persists the transaction, all copies of the RJSVM defined above will contain this blogpost
+
+datawriter.callEndpoint('submit', { 
+    title: "A underfunded blogpost", 
+    body: "Oh no this will never show up!", 
+    from: "#1 RJSVM User in the world" 
+})
+// Insufficient fee, the RJSVMs will not contain this blogpost. No refunds.
+
+datawriter.ownerSubmit('ownerSubmit', { 
+    title: "A underprivileged blogpost", 
+    body: "Oh no this will never show up!", 
+    from: "#1 RJSVM User in the world" 
+})
+// userWallet.address != ownerWallet.address, the RJSVMs will not contain this blogpost.
+```
+
+# [For a full list of examples please refer to the unit tests](https://gitea.nitowa.xyz/nitowa/RJSVM/src/branch/master/test/Test.ts)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rjsvm",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "",
   "main": "lib/main.js",
   "scripts": {

src/RJSVM/framework/rjsvm.ts

@@ -30,7 +30,6 @@ export abstract class RJSVM_Builder {
                 public readonly config: RJSVM_Config
             ) {
                 super()
-
                 
                 if(!XRP_ADDRESS.test(this.owner)){
                     const err = new Error(`Inavlid owner address ${this.owner}`)
@@ -38,7 +37,6 @@ export abstract class RJSVM_Builder {
                     throw err
                 }
                 
-
                 this.definitions = Object.freeze(defs)
                 Object.entries(this.definitions).forEach(([k, v]) => {
                     this[k] = (env: PaymentTx_T, ...args: any) => (v.implementation as ParameterizedFunction).apply(this as any, [env, ...args])
@@ -87,6 +85,7 @@ export abstract class RJSVM_Builder {
                 }
 
                 this.subscribers = {}
+                this.onceSubscribers = {}
             }
 
             public on = (event: string, handler: ParameterizedFunction) => {

test/Test.ts

@@ -1,7 +1,5 @@
 import { z } from "zod";
-import { RJSVM_Implementations, RJSVM_Interface, RJSVM, RJSVM_Config } from "../src/RJSVM/framework/types"
-import { DataParser, RJSVM_Builder } from "../src/main";
-import { xrp_transaction_hash_schema } from "../src/RJSVM/framework/schemas";
+import { DataParser, RJSVM_Builder, RJSVM_Implementations, RJSVM_Interface, RJSVM, RJSVM_Config } from "../src/main";
 
 //Test requirements
 import { assert, expect } from 'chai';