Overview


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 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

In order to provide a more robust environment and quasi-typesafe execution this package also requires 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

// 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
implements RJSVM_Interface {
owner = ownerWallet.address

state: State = {
blogposts: []
}
}

// Implement the program logic
const RJSVM_Contract: RJSVM_Implementations = {
// 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