Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,5 @@
- [ ] Rebased to the latest commit of the target branch (or merged it into my branch)
- Once you make the PR reviewable, please avoid force-pushing
- [ ] Updated the docs if needed
- [ ] Linked the [issues](https://github.com/0xSpaceShard/starknet-devnet-js/issues) resolvable by this PR - [linking info](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
- [ ] Linked the [issues](https://github.com/starknet-io/starknet-devnet-js/issues) resolvable by this PR - [linking info](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
- [ ] Updated the tests if needed; all passing - `npm test`
4 changes: 2 additions & 2 deletions .github/workflows/build-test-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ on:
branches: ["*"]

env:
DEVNET_VERSION: "0.8.1"
DEVNET_VERSION: "0.8.2"
DEVNET_DIR: "/tmp/devnet-ci-storage"
DEVNET_PATH: "/tmp/devnet-ci-storage/starknet-devnet"
FORKED_DEVNET_PORT: 5051
Expand Down Expand Up @@ -64,7 +64,7 @@ jobs:
- name: Download Devnet binary
run: |
mkdir -p ${DEVNET_DIR}
curl -sSfL https://github.com/0xSpaceShard/starknet-devnet/releases/download/v${DEVNET_VERSION}/starknet-devnet-x86_64-unknown-linux-gnu.tar.gz | tar -xvz -C ${DEVNET_DIR}
curl -sSfL https://github.com/starknet-io/starknet-devnet/releases/download/v${DEVNET_VERSION}/starknet-devnet-x86_64-unknown-linux-gnu.tar.gz | tar -xvz -C ${DEVNET_DIR}

- name: Start Anvil container
run: |
Expand Down
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Introduction

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

# Installation

Expand All @@ -14,15 +14,15 @@ npm i starknet-devnet

## Devnet compatibility

This library version is compatible with Devnet `v0.8.1`.
This library version is compatible with Devnet `v0.8.2`.

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

## Environment compatibility

This library is intended for use with Node.js, not in a browser environment. In browsers, you can only use [`DevnetProvider`](#connect-to-a-running-instance) for connecting to an already running Devnet instance, but you cannot [spawn a new Devnet](#spawn-a-new-devnet), because that relies on modules not present in the browser engine.

To enable the use of `DevnetProvider` in browser, you need to configure sources for modules otherwise reported as not found. See [this issue](https://github.com/0xSpaceShard/starknet-devnet-js/issues/26) and [this SO answer](https://stackoverflow.com/a/51669301) for more info, but generally, if using webpack, it should be enough to populate a config file with the desired polyfill implementations or with `false` values.
To enable the use of `DevnetProvider` in browser, you need to configure sources for modules otherwise reported as not found. See [this issue](https://github.com/starknet-io/starknet-devnet-js/issues/26) and [this SO answer](https://stackoverflow.com/a/51669301) for more info, but generally, if using webpack, it should be enough to populate a config file with the desired polyfill implementations or with `false` values.

# Usage

Expand All @@ -38,7 +38,7 @@ Assuming your machine has a supported OS (macOS or Linux) and supported architec
import { Devnet } from "starknet-devnet";

async function main() {
// Specify anything from https://github.com/0xSpaceShard/starknet-devnet/releases
// Specify anything from https://github.com/starknet-io/starknet-devnet/releases
// Be sure to include the 'v' if it's in the version name.
const devnet = await Devnet.spawnVersion("v0.6.1");
console.log(await devnet.provider.isAlive()); // true
Expand Down Expand Up @@ -129,7 +129,7 @@ In that case, you must take care of the spawned process after the program exits.

## 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/docs/category/running) about different ways of running Devnet.
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://starknet-io.github.io/starknet-devnet/docs/category/running) about different ways of running Devnet.

```typescript
import { DevnetProvider } from "starknet-devnet";
Expand All @@ -139,7 +139,7 @@ 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/docs/api#devnet-api), to interact via [Starknet JSON-RPC API](https://0xspaceshard.github.io/starknet-devnet/docs/api#starknet-api), use [starknet.js](https://www.starknetjs.com/).
Since this library only supports the [Devnet-specific API](https://starknet-io.github.io/starknet-devnet/docs/api#devnet-api), to interact via [Starknet JSON-RPC API](https://starknet-io.github.io/starknet-devnet/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:

Expand All @@ -155,11 +155,11 @@ 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/docs/postman). See [this example](https://github.com/0xSpaceShard/starknet-devnet-js/blob/master/test/l1-l2-postman.test.ts) for more info.
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://starknet-io.github.io/starknet-devnet/docs/postman). See [this example](https://github.com/starknet-io/starknet-devnet-js/blob/master/test/l1-l2-postman.test.ts) for more info.

## Transaction Proofs

Use the `proofs` property of `DevnetProvider` to prove INVOKE v3 transactions. This is useful for testing proof-aware flows in your application. See the [Devnet proofs documentation](https://0xspaceshard.github.io/starknet-devnet/docs/proofs) for more details on proof modes.
Use the `proofs` property of `DevnetProvider` to prove INVOKE v3 transactions. This is useful for testing proof-aware flows in your application. See the [Devnet proofs documentation](https://starknet-io.github.io/starknet-devnet/docs/proofs) for more details on proof modes.

**Note:** Before calling `proveTransaction`, Devnet requires at least 10 blocks to exist. Start Devnet with `--proof-mode devnet` to enable this feature.

Expand Down Expand Up @@ -199,7 +199,7 @@ console.log(proofResult.proof_facts); // Array of 9 hex strings
console.log(proofResult.l2_to_l1_messages); // L2 to L1 messages from simulation
```

See [this example](https://github.com/0xSpaceShard/starknet-devnet-js/blob/master/test/proofs.test.ts) for a complete test with transaction building and signing.
See [this example](https://github.com/starknet-io/starknet-devnet-js/blob/master/test/proofs.test.ts) for a complete test with transaction building and signing.

## Configuration modification and retrieval

Expand All @@ -213,11 +213,11 @@ console.log(await devnet.provider.getConfig().l2_gas_price_fri);

## Examples

See the [`test` directory](https://github.com/0xSpaceShard/starknet-devnet-js/tree/master/test) for more usage examples.
See the [`test` directory](https://github.com/starknet-io/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.
If you spot a problem or room for improvement, check if an issue for it [already exists](https://github.com/starknet-io/starknet-devnet-js/issues). If not, [create a new one](https://github.com/starknet-io/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

Expand Down
2 changes: 1 addition & 1 deletion RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Adaptation to starknet-devnet

When adapting to a new [starknet-devnet](https://github.com/0xSpaceShard/starknet-devnet) version, be sure to have replaced all occurrences of the previous version with the new one.
When adapting to a new [starknet-devnet](https://github.com/starknet-io/starknet-devnet) version, be sure to have replaced all occurrences of the previous version with the new one.

If possible, keep the semver of `starknet-devnet-js` the same as that of `starknet-devnet`.

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "starknet-devnet",
"version": "0.8.1",
"version": "0.8.2",
"description": "Starknet Devnet provider",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand All @@ -21,7 +21,7 @@
"author": "SpaceShard",
"repository": {
"type": "git",
"url": "git+https://github.com/0xSpaceShard/starknet-devnet-js.git"
"url": "git+https://github.com/starknet-io/starknet-devnet-js.git"
},
"keywords": [
"starknet",
Expand Down
8 changes: 4 additions & 4 deletions src/cheats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export class Cheats {
/**
* Deactivate using `stopImpersonateAccount`.
*
* https://0xspaceshard.github.io/starknet-devnet/docs/account-impersonation
* https://starknet-io.github.io/starknet-devnet/docs/account-impersonation
* @param address the address of a locally non-present account that you want to impersonate
*/
public async impersonateAccount(address: string): Promise<void> {
Expand All @@ -16,7 +16,7 @@ export class Cheats {
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/account-impersonation
* https://starknet-io.github.io/starknet-devnet/docs/account-impersonation
* @param address the address of a locally non-present account that you want to stop impersonating
*/
public async stopImpersonateAccount(address: string): Promise<void> {
Expand All @@ -28,14 +28,14 @@ export class Cheats {
/**
* Enables automatic account impersonation. Every account that does not exist in the local state will be impersonated. Deactivate using `stopAutoImpersonate`.
*
* https://0xspaceshard.github.io/starknet-devnet/docs/account-impersonation
* https://starknet-io.github.io/starknet-devnet/docs/account-impersonation
*/
public async autoImpersonate(): Promise<void> {
await this.rpcProvider.sendRequest("devnet_autoImpersonate");
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/account-impersonation
* https://starknet-io.github.io/starknet-devnet/docs/account-impersonation
*/
public async stopAutoImpersonate(): Promise<void> {
await this.rpcProvider.sendRequest("devnet_stopAutoImpersonate");
Expand Down
2 changes: 1 addition & 1 deletion src/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ export const DEFAULT_DEVNET_HOST = "127.0.0.1";
export const DEFAULT_DEVNET_PORT = 5050;
export const DEFAULT_DEVNET_URL = `http://${DEFAULT_DEVNET_HOST}:${DEFAULT_DEVNET_PORT}`;

export const LATEST_COMPATIBLE_DEVNET_VERSION = "v0.6.0";
export const LATEST_COMPATIBLE_DEVNET_VERSION = "v0.8.2";
22 changes: 11 additions & 11 deletions src/devnet-provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ export class DevnetProvider {

/**
* Restart the state of the underlying Devnet instance. You may opt to restart L1-L2 messaging.
* https://0xspaceshard.github.io/starknet-devnet/docs/dump-load-restart#restarting
* https://starknet-io.github.io/starknet-devnet/docs/dump-load-restart#restarting
*/
public async restart(params: { restartL1ToL2Messaging?: boolean } = {}): Promise<void> {
await this.rpcProvider.sendRequest("devnet_restart", {
Expand All @@ -90,7 +90,7 @@ export class DevnetProvider {

/**
* Generate funds at the provided address. For return spec and more info, see
* https://0xspaceshard.github.io/starknet-devnet/docs/balance#mint-token---local-faucet
* https://starknet-io.github.io/starknet-devnet/docs/balance#mint-token---local-faucet
* @param address the account address to receive funds
* @param amount how much to mint
* @param unit specifier of the currency unit; defaults to FRI
Expand All @@ -115,7 +115,7 @@ export class DevnetProvider {
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/predeployed#how-to-get-predeployment-info
* https://starknet-io.github.io/starknet-devnet/docs/predeployed#how-to-get-predeployment-info
* @returns a list of containing information on predeployed accounts. Load an account using e.g. starknet.js.
*/
public async getPredeployedAccounts(
Expand All @@ -127,15 +127,15 @@ export class DevnetProvider {
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/blocks
* https://starknet-io.github.io/starknet-devnet/docs/blocks
* @returns the block hash of the newly created block
*/
public async createBlock(): Promise<NewBlockResponse> {
return await this.rpcProvider.sendRequest("devnet_createBlock");
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/blocks
* https://starknet-io.github.io/starknet-devnet/docs/blocks
* @param staringBlockId the block ID of the block after which (inclusive) all blocks
* should be aborted. See docs {@link BlockId} for more info.
* @returns hash values of aborted blocks
Expand All @@ -147,7 +147,7 @@ export class DevnetProvider {
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/next/starknet-time#set-time
* https://starknet-io.github.io/starknet-devnet/docs/next/starknet-time#set-time
* @returns the new time in unix seconds and, if block creation requested, the hash of the created block
*/
public async setTime(
Expand All @@ -162,7 +162,7 @@ export class DevnetProvider {

/**
* Increase the time by the provided `increment` seconds.
* https://0xspaceshard.github.io/starknet-devnet/docs/next/starknet-time#increase-time
* https://starknet-io.github.io/starknet-devnet/docs/next/starknet-time#increase-time
* @returns the new time in unix seconds
*/
public async increaseTime(increment: number): Promise<IncreaseTimeResponse> {
Expand All @@ -172,7 +172,7 @@ export class DevnetProvider {
}

/**
* https://0xspaceshard.github.io/starknet-devnet/docs/dump-load-restart#dumping
* https://starknet-io.github.io/starknet-devnet/docs/dump-load-restart#dumping
* @param path the path where your Devnet instance will be serialized; if not provided, defaults to the dump-path provided via CLI on Devnet startup.
*/
public async dump(path?: string): Promise<void> {
Expand All @@ -181,15 +181,15 @@ export class DevnetProvider {

/**
* After loading, this DevnetProvider instance will be connected to the loaded Devnet instance.
* https://0xspaceshard.github.io/starknet-devnet/docs/dump-load-restart#dumping
* https://starknet-io.github.io/starknet-devnet/docs/dump-load-restart#dumping
* @param path the path from which a Devnet instance will be deserialized
*/
public async load(path: string): Promise<void> {
return await this.rpcProvider.sendRequest("devnet_load", { path });
}

/**
* Modify gas prices, according to https://0xspaceshard.github.io/starknet-devnet/docs/gas
* Modify gas prices, according to https://starknet-io.github.io/starknet-devnet/docs/gas
* @param price new gas prices; any gas price can be ommitted
* @param generateBlock if `true`, a new block is generated immediately, having new gas prices;
* otherwise (by default) the price change takes effect with the usual next block generation
Expand Down Expand Up @@ -221,7 +221,7 @@ export class DevnetProvider {
}

/**
* More info at: https://0xspaceshard.github.io/starknet-devnet/docs/api#config-api
* More info at: https://starknet-io.github.io/starknet-devnet/docs/api#config-api
* @returns the configuration of the underlying Devnet instance. The returned object is marked
* as `any` because it may change too often.
*/
Expand Down
2 changes: 1 addition & 1 deletion src/devnet.ts
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ The output location is configurable via the config object passed to the Devnet s
* If you already have a local Devnet you would like to run, use {@link spawnCommand}.
* @param version if set to `"latest"`, uses the latest Devnet version compatible with this library;
* otherwise needs to be a semver string with a prepended "v" (e.g. "v1.2.3") and
* should be available in https://github.com/0xSpaceShard/starknet-devnet/releases
* should be available in https://github.com/starknet-io/starknet-devnet/releases
* @param config configuration object
* @returns a newly spawned Devnet instance
*/
Expand Down
Loading