feat: add custom chain spec

[kratico]

Resolves #515

Update PolkadotDevProvider/ContractsDevProvider providers with a custom chain spec and add the /user_i endpoints

The custom chain spec add test accounts with an initial balance.

How to test?

Run the following example to validate that a test account has an initial balance.

import { System, users } from "polkadot_dev/mod.ts"

const [user0, _user1, _user2] = await users(3)

const result = await System.Account.entry([user0.publicKey]).run()

console.log(result)

To test the API

curl -X post http://localhost:4646/frame/dev/polkadot/@latest/user_i -d '{"count":2}'     
{"index":4}

curl -X post http://localhost:4646/frame/contracts_dev/@latest/user_i -d '{"count":2}'
{"index":2}

[kratico]

@harrysolovay @tjjfvi

I explored how to get unique tests users doing something like

import users from http://localhost:4646/frame/dev/polkadot/@v0.9.37/test_users.ts

But, this is a bit challenging given that

• deno caches the imports
• in the CAPI server, the polkadot instance is shared by all imports to the same provider

There are a few ways to bypass the deno cache, for example we can tweak the CAPI server to respond differently based on

• authorization header, DENO_AUTH_TOKENS=a1b2c3d4e5f6@localhost:4646 deno run script.ts, but it will need a different token on every run
• import {} from "http://localhost:4646/frame/dev/polkadot/@v0.9.37/test_users.ts?cacheId=1234, but it will need a different query string on every import

[tjjfvi]

Yeah, imports probably won't work well.

You'll want to add logic to the provider itself (override handle) to handle a request to a filePath of e.g. /testUsers?count=5 and return the relevant user ids.

Then, you'll want to add a custom function to the codegen to call this route. The easiest way will be to override chainFile to add a function like

type ArrayOfLength<
  T,
  L extends number,
  A extends T[] = [],
> = number extends L ? T[]
  : L extends A["length"] ? A
  : ArrayOfLength<T, L, [...A, T]>

export async function getTestUsers<N extends number>(count: N): Promise<ArrayOfLength<C.Sr25519, N>>
export async function getTestUsers(count: number): Promise<C.Sr25519[]> {
  const userIds: number[] = await fetch(`.../testUsers?count=${count}`).then(r => r.json())
  return userIds.map(C.testUser)
}

Then, it can be used like

import { getTestUsers } from "polkadot_dev"

const [alex, bill, carol] = await getTestUsers(3)

[kratico]

@tjjfvi I've just spoke with @harrysolovay and he suggested a similar approach.

Thank you both

[harrysolovay]

Should we model this as a Rune factory instead?

import { System, user } from "polkadot_dev/mod.ts"

const alice = user()

const result = await System.Account.value(alice.publicKey).run()

console.log(result)

And let's also make sure to include an ExceededMaximumTestUsersError... although I doubt anyone will exceed 1000. Is there much initialization overhead? Could we do 10000? 100000? ...

[tjjfvi]

We need it to persist state between runs, so it wouldn't work well as a rune at the moment.

[harrysolovay]

Ah, I see. Good point.

[kratico]

@tjjfvi @harrysolovay Would you give it a quick pass to validate the provider override handle and override chainFile implementations?

I'd like to get a quick feedback before refactoring them for the ContractsDevProvider

[kratico]

@tjjfvi @harrysolovay Shall I move these .handle and .chainFile overrides to the FrameBinProvider?

That way the ContractsDevProvider will have the test user API too

Thoughts?

[kratico]

@harrysolovay @tjjfvi I just realized that the ProjectProvider and the ZombienetProvider also extends from FrameBinProvider

So adding the overrides to .chainFile and .handle will work only for substrate based nodes because the assumption is that using the binary the chain spec could be generated with binary build-spec ....

Maybe I need to change the design by extracting the user testing stuff in a new class and then use composition instead of inheritance.

Thoughts?

[tjjfvi]

Perhaps we should just merge the dev and contracts providers

[kratico]

Perhaps we should just merge the dev and contracts providers

I've just meet with Harry and decided to add a common.ts module and extract createCustomChainSpec and fns related to handling test users.

[harrysolovay]

Last thing: per @tjjfvi's recommendation, let's actually return an error response here. Then we can delete the if (index === -1) check in the client users fn.