feat: scope (#1084)

Co-authored-by: Harry Solovay <harrysolovay@gmail.com>

Readme.md

@@ -97,8 +97,11 @@ Retrieve the first 10 entries from a storage map of Polkadot.
 
 ```ts
 import { polkadot } from "@capi/polkadot"
+import { Scope } from "capi"
 
-const accounts = await polkadot.System.Account.entries({ limit: 10 }).run()
+const accounts = await polkadot.System.Account
+  .entries({ limit: 10 })
+  .run(new Scope())
 ```
 
 ## Development Networks

examples/blocks.eg.ts

@@ -7,7 +7,7 @@
  */
 
 import { $eventRecord, metadata, polkadot } from "@capi/polkadot"
-import { $, $extrinsic, known, Rune } from "capi"
+import { $, $extrinsic, known, Rune, Scope } from "capi"
 import { babeBlockAuthor } from "capi/patterns/consensus"
 
 /// Reference the latest block hash.
@@ -38,7 +38,7 @@ const collection = await Rune
     events,
     author,
   })
-  .run()
+  .run(new Scope())
 
 /// Ensure that collection contains the expected shape of data.
 console.log("Collection:", collection)

examples/dev/metadata.eg.ts

@@ -12,8 +12,9 @@
  */
 
 import { polkadotDev } from "@capi/polkadot-dev"
+import { Scope } from "capi"
 
 /// Execute the metadata Rune.
-const metadata = await polkadotDev.metadata.run()
+const metadata = await polkadotDev.metadata.run(new Scope())
 
 console.log("Metadata:", metadata)

examples/dev/storage_sizes.eg.ts

@@ -8,11 +8,11 @@
  */
 
 import { polkadotDev } from "@capi/polkadot-dev"
-import { $ } from "capi"
+import { $, Scope } from "capi"
 import { storageSizes } from "capi/patterns/storage_sizes"
 
 /// Use the storageSizes factory to produce a Rune. Then execute it.
-const sizes = await storageSizes(polkadotDev).run()
+const sizes = await storageSizes(polkadotDev).run(new Scope())
 
 /// Ensure `sizes` is of the expected shape.
 console.log("Sizes:", sizes)

examples/dynamic.eg.ts

@@ -13,7 +13,7 @@
  * 3. Chain-specifics are untyped (be wary to supply the correct data, as the checker is on vacation).
  */
 
-import { $, ChainRune, WsConnection } from "capi"
+import { $, ChainRune, Scope, WsConnection } from "capi"
 
 /// We could also initialize a `ChainRune` with `WsConnection` and an RPC node WebSocket URL.
 const chain = ChainRune.from(WsConnection.bind("wss://rpc.polkadot.io"))
@@ -26,7 +26,7 @@ const Account = System.storage("Account")
 
 /// Read the first ten entries of the `Account` storage map.
 /// Note how the lack of partial key is communicated via `null`.
-const entries = await Account.entries({ limit: 10 }).run()
+const entries = await Account.entries({ limit: 10 }).run(new Scope())
 
 /// The result should contain a `[Uint8Array, AccountInfo]` tuple of length 10.
 console.log("Entries page:", entries)

examples/ink/deploy.eg.ts

@@ -7,7 +7,7 @@
  */
 
 import { contractsDev } from "@capi/contracts-dev"
-import { $, createDevUsers, hex, Sr25519, ss58 } from "capi"
+import { $, createDevUsers, hex, Scope, Sr25519, ss58 } from "capi"
 import { InkMetadataRune } from "capi/patterns/ink"
 import { signature } from "capi/patterns/signature/polkadot"
 
@@ -36,7 +36,7 @@ const events = await metadata
   .sent()
   .dbgStatus("Instantiation:")
   .inBlockEvents()
-  .run()
+  .run(new Scope())
 
 /// > Note: we're using `inBlockEvents` and not `finalizedEvents` because our provider
 /// > is configured with instant finality. This is optimal for testing, but not production.

examples/ink/interact.eg.ts

@@ -8,10 +8,12 @@
 
 import { contractsDev } from "@capi/contracts-dev"
 import { assert } from "asserts"
-import { $, createDevUsers, hex } from "capi"
+import { $, createDevUsers, hex, Scope } from "capi"
 import { InkMetadataRune } from "capi/patterns/ink"
 import { signature } from "capi/patterns/signature/polkadot"
 
+const scope = new Scope()
+
 /// Get two test users. Alexa will deploy, Billy will be the recipient of an erc20
 /// token transfer.
 const { alexa, billy } = await createDevUsers()
@@ -37,7 +39,7 @@ const state = contract.call({
 })
 
 /// Retrieve the initial state.
-const initialState = await state.run()
+const initialState = await state.run(scope)
 console.log("Alexa initial balance:", initialState)
 
 /// Use the `flip` method to *flip* the contract instance state.
@@ -52,7 +54,7 @@ const events = await contract
   .dbgStatus("Transfer:")
   .inBlockEvents()
   .pipe(contract.emittedEvents)
-  .run()
+  .run(scope)
 
 /// Ensure the emitted events are of the expected shape.
 /// In this case, we expect only a `Transfer` event.
@@ -70,7 +72,7 @@ $.assert(
 console.log(events)
 
 /// Retrieve the final state.
-const finalState = await state.run()
+const finalState = await state.run(scope)
 console.log("Alexa final balance:", finalState)
 
 assert(finalState < initialState)

examples/misc/identity.eg.ts

@@ -7,11 +7,12 @@
  */
 
 import { polkadotDev } from "@capi/polkadot-dev"
-import { $, createDevUsers, is } from "capi"
+import { $, createDevUsers, is, Scope } from "capi"
 import { IdentityInfoTranscoders } from "capi/patterns/identity"
 import { signature } from "capi/patterns/signature/polkadot"
 
 const { alexa } = await createDevUsers()
+const scope = new Scope()
 
 /// Initialize an `IdentityInfoTranscoders` of shape `{ stars: number }`.
 const transcoders = new IdentityInfoTranscoders({ stars: $.u8 })
@@ -29,15 +30,15 @@ await polkadotDev.Identity
   .sent()
   .dbgStatus("Set identity:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Retrieve and decode the identity info.
 const infoDecoded = await polkadotDev.Identity.IdentityOf
   .value(alexa.publicKey)
   .unhandle(is(undefined))
   .access("info")
   .pipe((raw) => transcoders.decode(raw))
-  .run()
+  .run(scope)
 
 console.log("identity info:", infoDecoded)
 $.assert($.u8, infoDecoded.additional.stars)

examples/misc/indices.eg.ts

@@ -7,12 +7,14 @@
 
 import { polkadotDev } from "@capi/polkadot-dev"
 import { assertEquals } from "asserts"
-import { createDevUsers, is } from "capi"
+import { createDevUsers, is, Scope } from "capi"
 import { signature } from "capi/patterns/signature/polkadot"
 
 const { alexa } = await createDevUsers()
+const scope = new Scope()
 
-const index = 254
+/// Generate a random (but reasonably large) index.
+const index = (crypto.getRandomValues(new Uint32Array([0]))[0]! | 4646) >>> 0
 
 /// Claim the index.
 const hash = await polkadotDev.Indices
@@ -21,14 +23,14 @@ const hash = await polkadotDev.Indices
   .sent()
   .dbgStatus("Claim index:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Use the index to key into the indices accounts map.
 const mapped = await polkadotDev.Indices.Accounts
   .value(index, hash)
   .unhandle(is(undefined))
   .access(0)
-  .run()
+  .run(scope)
 
 /// The retrieved mapped account id should be Alexa's.
 console.log(`Index ${index} Mapped to:`, mapped)

examples/multisig/basic.eg.ts

@@ -7,11 +7,12 @@
 
 import { polkadotDev } from "@capi/polkadot-dev"
 import { assert } from "asserts"
-import { $, createDevUsers, is } from "capi"
+import { $, createDevUsers, is, Scope } from "capi"
 import { MultisigRune } from "capi/patterns/multisig"
 import { signature } from "capi/patterns/signature/polkadot"
 
 const { alexa, billy, carol, david } = await createDevUsers()
+const scope = new Scope()
 
 /// Initialize the `MultisigRune` with Alexa, Billy and Carol. Set the passing threshold to 2.
 const multisig = MultisigRune.from(polkadotDev, {
@@ -26,7 +27,7 @@ const davidFree = polkadotDev.System.Account
   .access("data", "free")
 
 /// Execute the `davidFree` Rune.
-const davidFreeInitial = await davidFree.run()
+const davidFreeInitial = await davidFree.run(scope)
 console.log("David free initial:", davidFreeInitial)
 
 /// Transfer initial funds to the multisig (existential deposit).
@@ -36,7 +37,7 @@ await multisig
   .sent()
   .dbgStatus("Existential deposit:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Describe the call we wish to dispatch from the multisig.
 const call = polkadotDev.Balances.transferKeepAlive({
@@ -51,17 +52,17 @@ await multisig
   .sent()
   .dbgStatus("Proposal:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Check whether the call has been proposed.
-const isProposed = await multisig.isProposed(call.callHash).run()
+const isProposed = await multisig.isProposed(call.callHash).run(scope)
 console.log("Is proposed:", isProposed)
 assert(isProposed)
 
 const { approvals } = await multisig
   .proposal(call.callHash)
   .unhandle(is(undefined))
-  .run()
+  .run(scope)
 
 /// `approvals` should be a list of the approvers (account ids).
 console.log("Approvals:", approvals)
@@ -74,10 +75,10 @@ await multisig
   .sent()
   .dbgStatus("Final approval:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Check to see whether David's balance has in fact changed
-const davidFreeFinal = await davidFree.run()
+const davidFreeFinal = await davidFree.run(scope)
 console.log("David free final:", davidFreeFinal)
 
 /// The final balance should be greater than the initial.

examples/multisig/stash.eg.ts

@@ -7,12 +7,13 @@
 
 import { MultiAddress, polkadotDev } from "@capi/polkadot-dev"
 import { assert } from "asserts"
-import { createDevUsers, is } from "capi"
+import { createDevUsers, is, Scope } from "capi"
 import { MultisigRune } from "capi/patterns/multisig"
 import { filterPureCreatedEvents } from "capi/patterns/proxy"
 import { signature } from "capi/patterns/signature/polkadot"
 
 const { alexa, billy, carol } = await createDevUsers()
+const scope = new Scope()
 
 /// Initialize the `MultisigRune` with Alexa, Billy and Carol. Set the passing threshold to 2.
 const multisig = MultisigRune.from(polkadotDev, {
@@ -27,7 +28,7 @@ await multisig
   .sent()
   .dbgStatus("Existential deposit:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Describe the call which we wish to dispatch from the multisig account:
 /// the creation of the stash / pure proxy, belonging to the multisig account itself.
@@ -44,7 +45,7 @@ await multisig
   .sent()
   .dbgStatus("Proposal:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Approve the stash creation call and extract the pure creation event, which should
 /// contain its account id.
@@ -56,7 +57,7 @@ const stashAccountId = await multisig
   .finalizedEvents()
   .pipe(filterPureCreatedEvents)
   .access(0, "pure")
-  .run()
+  .run(scope)
 
 /// Send funds to the stash (existential deposit).
 await polkadotDev.Balances
@@ -68,14 +69,14 @@ await polkadotDev.Balances
   .sent()
   .dbgStatus("Fund Stash:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Ensure that the funds arrived successfully.
 const stashFree = await polkadotDev.System.Account
   .value(stashAccountId)
   .unhandle(is(undefined))
   .access("data", "free")
-  .run()
+  .run(scope)
 
 /// The stash's free should be greater than zero.
 console.log("Stash free:", stashFree)

examples/multisig/virtual.eg.ts

@@ -19,12 +19,13 @@
 
 import { MultiAddress, polkadotDev } from "@capi/polkadot-dev"
 import { assert } from "asserts"
-import { $, createDevUsers, is, Rune, Sr25519 } from "capi"
+import { $, createDevUsers, is, Rune, Scope, Sr25519 } from "capi"
 import { VirtualMultisigRune } from "capi/patterns/multisig"
 import { signature } from "capi/patterns/signature/polkadot"
 import { parse } from "../../deps/std/flags.ts"
 
 const { alexa, billy, carol, david } = await createDevUsers()
+const scope = new Scope()
 
 /// To reference a virtual multisig, one must have several pieces of data, including
 /// the member->proxy account id lookup, the threshold and the stash account id.
@@ -40,7 +41,7 @@ if (!state) {
       deployer: alexa.address,
     }, signature({ sender: alexa }))
     .hex
-    .run()
+    .run(scope)
 }
 
 console.log("State:", state)
@@ -59,7 +60,7 @@ await polkadotDev.Balances
   .sent()
   .dbgStatus("Fund stash:")
   .finalized()
-  .run()
+  .run(scope)
 
 /// Reference David's free balance.
 const davidFree = polkadotDev.System.Account
@@ -68,7 +69,7 @@ const davidFree = polkadotDev.System.Account
   .access("data", "free")
 
 /// Retrieve David's initial free.
-const davidFreeInitial = await davidFree.run()
+const davidFreeInitial = await davidFree.run(scope)
 console.log("David free initial:", davidFreeInitial)
 
 /// Describe the call we wish to dispatch from the virtual multisig's stash.
@@ -78,11 +79,11 @@ const call = polkadotDev.Balances.transfer({
 })
 
 /// Fund Billy and Carol's proxy accounts (existential deposits).
-await fundAndRatify("billy", billy).run()
-await fundAndRatify("carol", carol).run()
+await fundAndRatify("billy", billy).run(scope)
+await fundAndRatify("carol", carol).run(scope)
 
 /// Retrieve David's final balance.
-const davidFreeFinal = await davidFree.run()
+const davidFreeFinal = await davidFree.run(scope)
 console.log("David free final:", davidFreeFinal)
 
 // David's final balance should be greater than the initial.