Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/0xSpaceShard/starknet-devnet-js

Starknet Devnet provider
https://github.com/0xSpaceShard/starknet-devnet-js

devnet json-rpc l1-l2 l1-l2-conversation l2 starknet starkware

Last synced: 3 months ago
JSON representation

Starknet Devnet provider

Awesome Lists containing this project

README 

        
[![npm package](https://img.shields.io/npm/v/starknet-devnet?color=blue)](https://www.npmjs.com/package/starknet-devnet)



# Introduction



Using this JavaScript/TypeScript library, you can spawn [Starknet Devnet](https://github.com/0xSpaceShard/starknet-devnet-rs/) without installing and running it in a separate terminal. You can interact with it via its specific [Devnet API](https://0xspaceshard.github.io/starknet-devnet-rs/docs/api#devnet-api). To interact with any Starknet node or network (including Starknet Devnet) via the [Starknet JSON-RPC API](https://0xspaceshard.github.io/starknet-devnet-rs/docs/api#starknet-api), see [starknet.js](https://www.starknetjs.com/).



# Installation



```

npm i starknet-devnet

```



# Compatibility



This library is compatible with stable Devnet versions in the inclusive range: `v0.1.1`-`v0.1.2`.



[Devnet's balance checking functionality](https://0xspaceshard.github.io/starknet-devnet-rs/docs/balance#check-balance) is not provided in this library because it is simply replaceable using starknet.js, as witnessed by the [getAccountBalance function](./test/util.ts#L57)



# Usage



## Spawn a new Devnet



This library allows you to spawn a Devnet instance inside your program, without a separate terminal. It finds a random free port, and releases all used resources on exit. You can specify a port of your choice via `args: ["--port", ...]`.



### Spawn a version without manual installation



Assuming your machine has a supported OS (macOS or Linux) and supported architecture (arm64/aarch64 or x64/x86_64), using `Devnet.spawnVersion` will quickly install and spawn a new Devnet.



```typescript

import { Devnet } from "starknet-devnet";



async function main() {

    // Specify anything from https://github.com/0xSpaceShard/starknet-devnet-rs/releases

    // Be sure to include the 'v' if it's in the version name.

    const devnet = await Devnet.spawnVersion("v0.1.2");

    console.log(await devnet.provider.isAlive()); // true

}

```



To use the latest compatible version:



```typescript

const devnet = await Devnet.spawnVersion("latest");

```



### Spawn an already installed Devnet



Assuming you have already installed Devnet and it is present in your environment's `PATH`, simply run:



```typescript

const devnet = await Devnet.spawnInstalled();

```



### Specify Devnet arguments



You can use the same CLI arguments you would pass to a Devnet running in a terminal:



```typescript

const devnet = await Devnet.spawnInstalled({ args: ["--predeployed-accounts", "3"] });

```



### Devnet output



By default, the spawned Devnet inherits the output streams of the main program in which it is invoked. If you invoke your program in a terminal without any stream redirections, it will print Devnet logs in that same terminal together with your program output. This can be overriden:



```typescript

import fs from "fs";

const outputStream = fs.createWriteStream("devnet-out.txt");

const devnet = await Devnet.spawnInstalled({

    stdout: outputStream,

    stderr: /* what you will, could be the same as stdout */,

});

// do stuff with devnet and then close the stream

outputStream.end();

```



To track the output in a separate terminal, open a new terminal and run:



```

tail -f devnet-out.txt

```



To ignore the output completely, specify `{ stdout: "ignore", stderr: "ignore" }`.



### Spawn a custom build



If you have a custom build of Devnet or have multiple custom versions present locally:



```typescript

// provide the command

const devnet = await Devnet.spawnCommand("my-devnet-command", { ... });

// or specify the path

const devnet = await Devnet.spawnCommand("/path/to/my-devnet-command", { ... });

```



### Killing



By default, the Devnet subprocess automatically exits and releases the used resources on program end, but you can send it a signal if needed:



```typescript

const devnet = await Devnet.spawnInstalled();

devnet.kill(...); // defaults to SIGTERM

```



### Keeping alive



To keep the spawned Devnet alive after your program exits, set the `keepAlive` flag:



```typescript

const devnet = await Devnet.spawnInstalled({ keepAlive: true });

```



In that case, you must take care of the spawned process after the program exits. To kill it, you need to:



1. Know the port it is using. It is logged on Devnet startup and is also a part of `devnet.provider.url`.

2. Kill the process using the port, which you can do:



    a. In JS, by relying on the [cross-port-killer library](https://www.npmjs.com/package/cross-port-killer).



    b. From shell, by executing `lsof -i : | awk 'NR==2{print $2}' | xargs kill` (substitute `` with yours).



## Connect to a running instance



If there already is a running Devnet instance (e.g. in another terminal or in another JS/TS program), you can simply connect to it by importing `DevnetProvider`. [Read more](https://0xspaceshard.github.io/starknet-devnet-rs/docs/category/running) about different ways of running Devnet.



```typescript

import { DevnetProvider } from "starknet-devnet";

const devnet = new DevnetProvider(); // accepts an optional configuration object

console.log(await devnet.isAlive()); // true

```



## Enabling Starknet API support



Since this library only supports the [Devnet-specific API](https://0xspaceshard.github.io/starknet-devnet-rs/docs/api#devnet-api), to interact via [Starknet JSON-RPC API](https://0xspaceshard.github.io/starknet-devnet-rs/docs/api#starknet-api), use [starknet.js](https://www.starknetjs.com/).



E.g. to get the latest block after spawning Devnet, you would need to do:



```typescript

import { Devnet } from "starknet-devnet";

import * as starknet from "starknet";



const devnet = await Devnet.spawnInstalled();

const starknetProvider = new starknet.RpcProvider({ nodeUrl: devnet.provider.url });



const block = await starknetProvider.getBlock("latest");

```



## L1-L2 communication



Assuming there is an L1 provider running (e.g. [anvil](https://github.com/foundry-rs/foundry/tree/master/crates/anvil)), use the `postman` property of `DevnetProvider` to achieve [L1-L2 communication](https://0xspaceshard.github.io/starknet-devnet-rs/docs/postman). See [this example](https://github.com/0xSpaceShard/starknet-devnet-js/blob/master/test/postman.test.ts) for more info.



## Examples



See the [`test` directory](https://github.com/0xSpaceShard/starknet-devnet-js/tree/master/test) for more usage examples.



## Contribute



If you spot a problem or room for improvement, check if an issue for it [already exists](https://github.com/0xSpaceShard/starknet-devnet-js/issues). If not, [create a new one](https://github.com/0xSpaceShard/starknet-devnet-js/issues/new). You are welcome to open a PR yourself to close the issue. Once you open a PR, you will see a template with a list of steps - please follow them.



### Test



Before running the tests with `npm test`, follow the steps defined in the [CI/CD config file](.circleci/config.yml). If your new test relies on environment variables, load them with `getEnvVar`. Conversely, to find all environment variables that need to be set before running existing tests, search the repo for `getEnvVar`.