npm package: @ledgerswarm/ls_participant_sdk
Description: An SDK for Ledgerswarm participant
Author: SETL
Latest version: 2.0.5

# LEDGERSWARM SDK

> SDK for triggering actions on the RLN 

## Prerequisites

This project requires NodeJS (developed on v18) and NPM.
[Node](http://nodejs.org/) and [NPM](https://npmjs.org/) are really easy to install.
To make sure you have them available on your machine,
try running the following command.

```sh
$ npm -v && node -v
8.19.2
v18.12.1
```

## Table of contents

- [Project Name](#project-name)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Usage](#usage)
- [License](#license)

## Getting Started

Set up a new nodejs project in your development environment and install the library as follows

```sh
$ npm install @ledgerswarm/ls_sdk
```

## Usage for Ping

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // ping your own node and return the username

    console.log('[ping.ping]')
    res = await Part.ping.ping()
    console.log(res)
    console.log('------------------')

    // ping your node without authentication

    console.log('[ping.openPing]')
    res = await Part.ping.openPing()
    console.log(res)
    console.log('------------------')

    // ping your node and return details of the components running

    console.log('[ping.participantPing]')
    res = await Part.ping.participantPing()
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Users

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show a specific user

    console.log("[user.users - GET]");
    res = await Part.user.user("GET", "antbank");
    console.log(res);
    console.log("------------------");

    // create a new user

    console.log("[user.user - POST]");
    res = await Part.user.user("POST", "username", {
    username: "username",
    password: "change-me",
    isAdmin: false,
    });
    console.log(res);
    console.log("------------------");

    // update an existing user

    console.log("[user.user - PUT]");
    res = await Part.user.user("PUT", "username", {
    username: "username",
    password: "change-me",
    isAdmin: true,
    });
    console.log(res);
    console.log("------------------");

    // delete a user

    console.log("[user.user - DELETE]");
    res = await Part.user.user("DELETE", "username");
    console.log(res);
    console.log("------------------");

    // change a user's password

    console.log("[user.password]");
    res = await Part.user.password("username", { password: "password" });
    console.log(res);
    console.log("------------------");

}

testParticipant()
```

## Usage for Accounts

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show all accounts

    console.log('[account.accountIds]')
    res = await Part.account.accountIds()
    console.log(res)
    console.log('------------------')

    // show all accounts of type DEFAULT

    console.log('[account.accountIds/{accountType}]')
    res = await Part.account.accountIds("GET",{accountType:'DEFAULT'})
    console.log(res)
    console.log('------------------')

    // show all instruments that are held by the account Alice

    console.log('[account.accountIds/{accountType}/{accountId}]')
    res = await Part.account.accountIds("GET",{accountType:'DEFAULT',accountId:'Alice'})
    console.log(res)
    console.log('------------------')

    // show a detailed view of the account Alice for the instrument USD

    console.log('[account.accountIds/{accountType}/{accountId}/{assetId}]')
    res = await Part.account.accountIds("GET",{accountType:'NOSTRO',accountId:'DOMAIN⑆CENTRAL⑈antbankaccount',assetId:'USD'})
    console.log(res)
    console.log('------------------')

    // show all pending transactions for the account Alice for the instrument USD

    console.log('[account.accountIds/{accountType}/{accountId}/{assetId}/pending]')
    res = await Part.account.accountPending("GET",{accountType:'DEFAULT',accountId:'Alice',assetId:'USD'})
    console.log(res)
    console.log('------------------')

    // set a balance for the account Bobby for the instrument USD

    console.log('[account.accountIds/{accountType}/{accountId}/{assetId}]')
    res = await Part.account.accountIds("POST",{accountType:'DEFAULT',accountId:'Bobby',assetId:'USD', amount:10, isDelta:true, reason:'test'})
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Instruments

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show all instruments

    console.log('[instrument.intsrument]')
    res = await Part.instrument.instrument()
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for NostroVostro

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show all nostro accounts

    console.log('[nostroVostro.nostroVostro]')
    res = await Part.nostroVostro.nostroVostro()
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Routes

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show all routes
    
    console.log('[router.route]')
    res = await Part.router.route()
    console.log(res)
    console.log('------------------')

    // show a route with a specific id

    console.log('[router.route/{id}]')
    res = await Part.router.route("GET",{id:3})
    console.log(res)
    console.log('------------------')

    // query a route with a specific asset and account

    console.log('[router.routeQuery]')
    res = await Part.router.routeQuery("GET",{asset:"USD", account:"Alice"})
    console.log(res)
    console.log('------------------')

    // create a new route

    console.log('[router.route PUT]')
    res = await Part.router.route("PUT",{ asset:"BP Shares", account:"antcustodyaccount", domain:'DOMAIN', match:'/.*/', participant:'BEEBANK'})
    console.log(res)
    let saveId=res.id
    console.log('------------------')

    // show all routes

    console.log('[router.route]')
    res = await Part.router.route()
    console.log(res)
    console.log('------------------')

    // delete a route

    console.log('[router.route DELETE]')
    res = await Part.router.route("DELETE",{id:saveId})
    console.log(res)
    console.log('------------------')

    // show all routes

    console.log('[router.route]')
    res = await Part.router.route()
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Propose

```js
cconst participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // propose a transaction 
    
    let manifestId = Math.random().toString(36).substring(2, 8);
    let transferId = Math.random().toString(36).substring(2, 8);

    console.log("[propose.manifest]");
    res = await Part.propose.manifest({
    manifestId: manifestId,
    transfers: [
        {
        amount: 11,
        assetId: "USD",
        from: {
            account: "Alice",
            domain: "TRANQUILITY",
            participant: "ANTBANK",
        },
        to: {
            account: "Bob",
            domain: "TRANQUILITY",
            participant: "ANTBANK",
        },
        transferId: transferId,
        },
    ],
    });
    console.log(res);
    console.log("------------------");

}

testParticipant()
```

## Usage for Approval or Rejection

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // accept a manifest with a given swarmId

    console.log('[manifest.approveManifest]')
    let swarmId = 'abcdef'
    res = await Part.manifest.approveManifest(swarmId) 
    console.log(res)
    console.log('------------------')

    // reject a manifest with a given swarmId
   
    console.log('[manifest.rejectManifest]')
    res = await Part.manifest.rejectManifest(swarmId)
    console.log(res)
    console.log('------------------')

    // search for a manifest
    
    /*
        Parmeters:

        swarmId: 
        requestId: 
        correlationId:
        createdAfter:
        createdBefore:
        scope:
        offeset:
        limit

        createdBefore: and createdAfter: This may be provided as a ISO-8601 timestamp indicating an 
        absolute time, or as an ISO-8601 duration indicating a time-before-present.

        scope: Available values : ACTIVE, ALL, FINALISED

    */
    
    console.log('[manifest.search]')
    res = await Part.manifest.search({"scope": "ALL"})
    console.log(res)
    console.log('------------------')

    // get a manifest with a given swarmId

    console.log('[manifest.selectManifest]')
    res = await Part.manifest.selectManifest({"swarmId":1})
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Approver Rules

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // show all approver rules

    console.log('[rule.rule]')
    res = await Part.rule.rule("GET",{})
    console.log(res)
    console.log('------------------')

    // create a new rule

    console.log('[router.route PUT]')

    let params={
        name:"ruleName",
        priority:200,
        text:"if(amount == 11) { return MANUAL; }",
        scope:"T"
    }

    res = await Part.rule.rule("PUT",params)
    console.log(res)
    let saveId=res.id
    console.log('------------------')

    // show all rules

    console.log('[rule.rule]')
    res = await Part.rule.rule("GET",{})
    console.log(res)
    console.log('------------------')

    // delete a rule

    console.log('[router.route DELETE]')
    res = await Part.router.route("DELETE",{id:3})
    console.log(res)
    console.log('------------------')

    // show all rules

    console.log('[rule.rule]')
    res = await Part.router.route("GET",{})
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Consensus

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // propose a consensus transaction 

    let correlationId = Math.random().toString(36).substring(2, 8);
    let payload_identifier = Math.random().toString(36).substring(2, 8);
    let timeout = 300;
    let expiry = Math.floor(Date.now()/1000) + (timeout*1);

    console.log("[consensus.consensus] PUT");

    let consensusParams = {
        "correlationId": correlationId,                           // provided by user. Collectively the message needs to be unique
        "observer": [                                             // list of entities observing the consensus also get final result
            {
                "entity_id": "CENTRAL",
                "domain_name": "TRANQUILITY"
            }
        ],
        "required": [                                             // all required parties must vote
            {
                "entity_id": "ANTBANK",
                "domain_name": "TRANQUILITY"
            },
            {
                "entity_id": "BEEBANK",
                "domain_name": "TRANQUILITY"
            }
        ],
        "optional": [                                             // optional parties can vote
            {
                "entity_id": "BANKA",
                "domain_name": "TRANQUILITY"
            }
        ],
        "payload": "IkNvbnRyYWN0IE5vIDEzMzMyIg==",                // can be anything
        "payload_format": "text/plain",                           // only used by receiver
        "payload_identifier": payload_identifier,                 // whatever you want - used by participants
        "threshold_approve": 0,                                   // number of approvals required 0 = all required
        "threshold_reject": 0,                                    // number of rejections it can withstand
        "timeout": expiry,                                        // unix timestamp seconds
        "context": "CONTEXT"                                      // settlement context - this is fed into a query parameter in the api ?sc=CONTEXT
    }

    console.log(consensusParams);
    res = await Part.consensus.consensus("PUT", consensusParams);
    console.log(res);
    console.log("------------------");

    // get consensus transactions

    console.log('[consensus.consensus] GET')
    let ISOsince = "PT"+1+"H" //ISO-8601 1 hour before present
    res= await Part.consensus.consensus("GET", {since:ISOsince});
    console.log(res)
    console.log('------------------')

    // approve a consensus transaction

    console.log('[consensus.approve]')
    swarmId = "abcdef" // should be a valid swarmId
    res = await Part.consensus.approve(swarmId);
    console.log(res)
    console.log('------------------')

    // reject a consensus transaction

    console.log('[consensus.reject]')
    swarmId = "abcdef" // should be a valid swarmId
    res = await Part.consensus.reject(swarmId);
    console.log(res)
    console.log('------------------')

    // show all consensus rules

    console.log('[consensus.rule]')
    res = await Part.consensus.rule("GET",{}) 
    console.log(res)
    console.log('------------------')

    // create a new consensus rule

    console.log('[consensus.rule PUT]')

    let params={
        name:"rname",
        priority:10,
        text:'if ( correlationId !^ "REJECT" ) { return REJECT; }',
        scope:"T"
    }

    res = await Part.consensus.rule("PUT",params)
    console.log(res)
    console.log('------------------')

    // delete a consensus rule

    console.log('[consensus.rule DELETE]')
    res = await Part.router.route("DELETE",{id:3})
    console.log(res)
    console.log('------------------')

}

testParticipant()
```

## Usage for Trace

```js
const participant = require ('ls-participant-sdk')
let server = 'server.setllabs.io'

async function testParticipant(){

    const UnAuthedPart = new participant(server);
    let res = await UnAuthedPart.auth.authenticate("POST", {
        userName: 'username',
        password: 'password',
    });

    let token = res.token;

    const Part = new participant(server, token);

    // trace the a settlement would take
    
    let manifestId = Math.random().toString(36).substring(2, 8);
    let transferId = Math.random().toString(36).substring(2, 8);

    console.log("[router.trace]");
    res = await Part.router.trace({
    manifestId: manifestId,
    transfers: [
        {
        amount: 11,
        assetId: "USD",
        from: {
            account: "Alice",
            domain: "TRANQUILITY",
            participant: "ANTBANK",
        },
        to: {
            account: "Bob",
            domain: "TRANQUILITY",
            participant: "BEEBANK",
        },
        transferId: transferId,
        },
    ],
    });
    console.log(res);
    console.log("------------------");

}

testParticipant()
```


## License

[MIT License](https://andreasonny.mit-license.org/2019)