{"id":25707629,"url":"https://github.com/tgrospic/rnode-grpc-js","last_synced_at":"2025-04-30T14:11:36.223Z","repository":{"id":45354624,"uuid":"203782317","full_name":"tgrospic/rnode-grpc-js","owner":"tgrospic","description":"RNode gRPC/HTTP API generator for Nodejs and the browser","archived":false,"fork":false,"pushed_at":"2022-12-09T23:39:46.000Z","size":870,"stargazers_count":9,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-18T12:22:39.703Z","etag":null,"topics":["api","client","generator","grpc","rchain","rnode","rnode-grpc","testnet","typescript"],"latest_commit_sha":null,"homepage":"https://tgrospic.github.io/rnode-grpc-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgrospic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-22T11:36:23.000Z","updated_at":"2022-01-09T00:56:15.000Z","dependencies_parsed_at":"2023-01-26T00:31:47.373Z","dependency_job_id":null,"html_url":"https://github.com/tgrospic/rnode-grpc-js","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrospic%2Frnode-grpc-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrospic%2Frnode-grpc-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrospic%2Frnode-grpc-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrospic%2Frnode-grpc-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgrospic","download_url":"https://codeload.github.com/tgrospic/rnode-grpc-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251390984,"owners_count":21582086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","generator","grpc","rchain","rnode","rnode-grpc","testnet","typescript"],"created_at":"2025-02-25T08:19:38.315Z","updated_at":"2025-04-30T14:11:36.178Z","avatar_url":"https://github.com/tgrospic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RNode gRPC API generator\n\nThis library helps to generate **JavaScript** bindings for **RNode gRPC API**.\n\nExamples of how to use it with **Nodejs** and in the **browser** are in [@tgrospic/rnode-client-js](https://github.com/tgrospic/rnode-client-js) repository.\n\nRNode also exposes **HTTP** natively with **RNode Web API**, for more information see [@tgrospic/rnode-http-js](https://github.com/tgrospic/rnode-http-js).\n\n__Deploys sent via Web API still have to be serialized with protobuf, but it's not necessary to use this library and generate any JS code. [rnode-sign.ts](src/rnode-sign.ts) can be used independently in your web project.__\n\n_gRPC is not supported in the browser but it can be used with the proxy. Here is the example of [Envoy configuration](https://github.com/grpc/grpc-web/blob/952d0f5869b315039a994011ecb5bf57dfdea999/net/grpc/gateway/examples/helloworld/envoy.yaml) to run your own _HTTP/gRPC_ proxy._\n\n\n#### It contains two parts:\n- `rnode-grpc` CLI to generate JS files with **TypeScript definitions**\n- helper functions to create **JS client** with **Promise** based **RNode** service methods.\n\n## Install\n\n```sh\nnpm install @tgrospic/rnode-grpc-js\n\n# gRPC and protobuf for use with Nodejs\n# - compatible with native `grpc` package\nnpm install google-protobuf @grpc/grpc-js\n# Or for use in the browser (via Envoy proxy)\nnpm install google-protobuf grpc-web\n\n# For crypto operations (create private key)\nnpm install elliptic\n```\n\nInstall peer dependencies needed to generate JS files from proto definitions.\n\n```sh\nnpm install --save-dev grpc-tools protobufjs\n```\n\n## Generate JS files\n\nThe purpose of `rnode-grpc` CLI command is to download and generate necessary files.\n\n```sh\n# Generate all files with default options (run from your package.json scripts)\nrnode-grpc\n\n# Generate with specific options\nrnode-grpc --rnode-version v0.12.4 --gen-dir ./rnode-grpc-gen\n\n# Run from your project folder\nnode_modules/.bin/rnode-grpc\n```\n## CLI options\n\n| Option             | Default            | Description\n| -------------------| ------------------ | ------------\n| --rnode-version    | `v0.12.4`          | Version (repo tag) of RNode to generate API.\n| --gen-dir          | `./rnode-grpc-gen` | Path to output directory.\n\n\u003cdetails\u003e\n\u003csummary\u003eAdditional use for RNode version option\u003c/summary\u003e\n\nWe can generate API from not yet published RNode version. From any branch on [rchain/rchain](https://github.com/rchain/rchain) repo, e.g. `dev` branch.\n\n```sh\nrnode-grpc --rnode-version dev\n```\nAnd make requests to new _DeployService_ method `isFinalized`. :smile:\n\n```typescript\ninterface DeployService {\n  // Not yet available in v0.9.12 RNode\n  isFinalized(_?: IsFinalizedQuery): Promise\u003cIsFinalizedResponse\u003e\n  // ...existing methods\n}\n```\n\u003c/details\u003e\n\n## API\n\nComplete API is combined from the part provided by the library and the generated part for a specific version of RNode.\n\nDocumentation for library part can be found here [https://tgrospic.github.io/rnode-grpc-js/](https://tgrospic.github.io/rnode-grpc-js/) and generated part with TypeScript definitions can be found in a directory specified by `--gen-dir` option.\n\nMore info for client options for [@grpc/grpc-js](https://github.com/grpc/grpc-node/blob/b05caec/packages/grpc-js/src/client.ts#L67) and [grpc-web](https://github.com/grpc/grpc-web/blob/8b501a96f/javascript/net/grpc/web/grpcwebclientbase.js#L45).\n\n```typescript\ninterface Options {\n  // gRPC protocol implementation\n  // - `@grpc/grpc-js` for Nodejs\n  // - `grpc-web` for browser\n  grpcLib: any\n  // Custom options for gRPC clients\n  // - `credentials` can be supplied as part of `clientOptions` for `grpc-js`\n  clientOptions?: any,\n  // RNode host (method prefix)\n  host: string,\n  // Generated JSON schema\n  protoSchema: Object\n}\n\n// Get deploy service methods\nrnodeDeploy(opt: Options): DeployService\n\n// Get propose service methods\nrnodePropose(opt: Options): ProposeService\n\n// Get repl service methods\nrnodeRepl(opt: Options): Repl\n\n// Get all service methods\nrnodeService(opt: Options): DeployService \u0026 ProposeService \u0026 Repl\n\n// Sign deploy data\nsignDeploy(key: string | Uint8Array | Buffer | ec.KeyPair, deploy: UnsignedDeployData): DeployDataProto\n\n// Verify deploy signature\nverifyDeploy(deploy: DeployDataProto): Boolean\n\n// Protobuf serialize / deserialize operations\nrnodeProtobuf({protoSchema}): TypesBinary\n\n// Transform Par type to JSON (with meaningful defaults)\nrhoParToJson(input: Par): any\n```\n\n### TypeScript definitions\n\nHere is an example of [TypeScript definition file](docs/rnode-grpc-js-v0.12.4.d.ts) generated for `v0.12.4` version of RNode.\n\n```sh\n# Run CLI command with an option to specify RNode version (Git repo release tag)\nrnode-grpc --rnode-version v0.12.4\n```\n_Generated TypeScript definitions are complete with the conversion of response errors inside the message to `Promise` errors. For RNode after `v0.9.14` version `ServiceError` type is converted and on previous versions the same conversion is done on a _dynamic_ `Either` type._ :smile:\n\n```typescript\n// Typescipt generated interface from RNode v0.12.4 protbuf definitions\ninterface DeployService {\n  doDeploy(_?: DeployDataProto): Promise\u003cDeployResponse\u003e\n  getBlock(_?: BlockQuery): Promise\u003cBlockResponse\u003e\n  visualizeDag(_?: VisualizeDagQuery): Promise\u003cVisualizeBlocksResponse[]\u003e\n  machineVerifiableDag(_?: MachineVerifyQuery): Promise\u003cMachineVerifyResponse\u003e\n  showMainChain(_?: BlocksQuery): Promise\u003cBlockInfoResponse[]\u003e\n  getBlocks(_?: BlocksQuery): Promise\u003cBlockInfoResponse[]\u003e\n  listenForDataAtName(_: DataAtNameQuery): Promise\u003cListeningNameDataResponse\u003e\n  listenForContinuationAtName(_: ContinuationAtNameQuery): Promise\u003cContinuationAtNameResponse\u003e\n  findDeploy(_?: FindDeployQuery): Promise\u003cFindDeployResponse\u003e\n  previewPrivateNames(_?: PrivateNamePreviewQuery): Promise\u003cPrivateNamePreviewResponse\u003e\n  lastFinalizedBlock(_?: LastFinalizedBlockQuery): Promise\u003cLastFinalizedBlockResponse\u003e\n  isFinalized(_?: IsFinalizedQuery): Promise\u003cIsFinalizedResponse\u003e\n  bondStatus(_?: BondStatusQuery): Promise\u003cBondStatusResponse\u003e\n  exploratoryDeploy(_?: ExploratoryDeployQuery): Promise\u003cExploratoryDeployResponse\u003e\n  getBlocksByHeights(_?: BlocksQueryByHeight): Promise\u003cBlockInfoResponse[]\u003e\n  getEventByHash(_?: ReportQuery): Promise\u003cEventInfoResponse\u003e\n}\n```\n\n## Sample code for gRPC requests to RNode\n\n_NOTE: RNode also exposes **HTTP** natively with **RNode Web API**, for more information see [@tgrospic/rnode-http-js](https://github.com/tgrospic/rnode-http-js)._\n\nUsing gRPC in the browser is not supported but it's possible with gRPC-HTTP proxy and [grpc-web](https://github.com/grpc/grpc-web) library.\n\nWorking version of these examples can be found in [@tgrospic/rnode-client-js/src/nodejs](https://github.com/tgrospic/rnode-client-js/tree/master/src/nodejs).\n\n```typescript\n/// \u003creference path=\"../rnode-grpc-gen/js/rnode-grpc-js.d.ts\" /\u003e\nimport grpcLib from '@grpc/grpc-js'\n// import grpcLib from 'grpc-web' // when using gRPC-HTTP proxy\nimport { ec } from 'elliptic'\nimport { rnodeDeploy, rnodePropose, signDeploy, verifyDeploy, LightBlockInfo } from '@tgrospic/rnode-grpc-js'\n\n// Generated files with rnode-grpc-js tool\nimport protoSchema from '../rnode-grpc-gen/js/pbjs_generated.json'\n// Import generated protobuf types (in global scope)\nimport '../rnode-grpc-gen/js/DeployServiceV1_pb'\nimport '../rnode-grpc-gen/js/ProposeServiceV1_pb'\n\n// RNode validator address (or any read-only RNode if we don't use _deploy_ and _propose_)\nconst rnodeExternalUrl = 'node2.testnet.rchain.coop:40401'\n// const rnodeInternalUrl = 'localhost:40402'\n// const rnodeExternalUrl = 'https://\u003chost\u003e:\u003cport\u003e' // when using gRPC-HTTP proxy\n\n// gRPC client options\nconst options = { grpcLib: grpcLib, host: rnodeExternalUrl, protoSchema }\n\n// Get RNode service methods\nconst { getBlocks, DoDeploy } = rnodeDeploy(options)\nconst { propose }             = rnodePropose(options)\n\n// Get blocks from RNode\nconst blocks: LightBlockInfo[] = await getBlocks({ depth: 2 })\n\n// Generate sample KeyPair (private/public keys) to sign the deploy\nconst secp256k1 = new ec('secp256k1')\nconst key = secp256k1.genKeyPair()\n// Or use existing as hex string or Uint8Array\n// const key = '1bf36a3d89c27ddef7955684b97667c75454317d8964528e57b2308947b250b0'\n\n// Sample Rholang code we want to deploy\nconst deployData = {\n  term: 'new out(`rho:io:stdout`) in { out!(\"Browser deploy test\") }',\n  timestamp: Date.now(),      // nonce\n  phloprice: 1,               // price of tinny REV for phlogiston (gas)\n  phlolimit: 10e3,            // max phlogiston (gas) for deploy execution\n  validafterblocknumber: 123, // latest block number\n}\n\n// Helper function to sign a deploy\n// - this can be done when offline and save the signed deploy as JSON\nconst deploy = signDeploy(key, deployData)\n\n// and to check the signature\nconst isValidDeploy = verifyDeploy(deploy)\n\n// Send signed deploy to RNode\nconst { message } = await DoDeploy(deploy)\n\n// Propose deploys to the rest of the network\n// - this is done by the validator and allowed only on internal (private) port\nawait propose()\n\n// Get result from deploy (after deploy is added to a block)\nconst { payload: { blockinfoList } } = await listenForDataAtName({\n  depth: 1,\n  name: { unforgeablesList: [{gDeployIdBody: { sig: deploy.sig }}] },\n})\n```\n### Protobuf serialize and deserialize operations\n\nThe small wrapper `rnodeProtobuf` allows easier access to protobuf generated types and serialize/deserialize operations.\n\n```typescript\n/// \u003creference path=\"../rnode-grpc-gen/js/rnode-grpc-js.d.ts\" /\u003e\n// Generated protobuf files must be loaded to instantiate a global proto object\n// needed for `rnodeProtobuf`\nrequire('../rnode-grpc-gen/js/DeployServiceV1_pb')\nrequire('../rnode-grpc-gen/js/ProposeServiceV1_pb')\nrequire('../rnode-grpc-gen/js/repl_pb')\nconst protoSchema = require('../rnode-grpc-gen/js/pbjs_generated.json')\n\nconst { rnodeProtobuf } = require('@tgrospic/rnode-grpc-js')\n\n// Get types with serialize and deserialize operations\nconst { DeployDataProto, CmdRequest } = rnodeProtobuf({ protoSchema })\n\nconst deployBytes = DeployDataProto.serialize({ term: 'Nil', phlolimit: 1000 })\n\nconst deployObj: DeployDataProto = DeployDataProto.deserialize(deployBytes)\n```\n\n## What is the difference with RChain-API?\n\nThe main difference is that this library does not depend on any specific version of RNode nor the schema definition (with minor caveats). RNode version is an input parameter and the goal is to generate JS and TS code for any RNode version.\n\n## Example for Node.js (with web)\n\nSample static site to test requests from the browser\n[https://tgrospic.github.io/rnode-client-js](https://tgrospic.github.io/rnode-client-js). It's published as part of the example repository [@tgrospic/rnode-client-js](https://github.com/tgrospic/rnode-client-js). It also contains protobuf/gRPC examples for Node.js.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgrospic%2Frnode-grpc-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgrospic%2Frnode-grpc-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgrospic%2Frnode-grpc-js/lists"}