* Support for metadata v13
* Lint fixes
* Lastest tag as string
* Documentation
* MagicNumber opt
* NMap enum entry
* NMapTypeLatest
* Adjust for NMap type overrides
* Static from v13
* Basic NMap support
* lint
* Test expectations
The Abi constructor used to take the registry as a parameter, now it takes registry.getChainProperties() and this change introduced hard to debug behaviour
* fix the autoaggregation of contract events
apparently, the system event for contract emitted events has had its name changed
* fix the autoaggregation of contract events
apparently, the system event for contract emitted events has had its name changed
* Update packages/api-contract/src/base/Contract.ts
* Apply suggestions from code review
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
* modified api-derive balances to allow use of custom balance storages via derives; current implementation only works with standard call signatures
* type predicate as filter value
* renamed derive method name
* modified api-derive balances to allow use of custom balance storages via derives; current implementation only works with standard call signatures
* type predicate as filter value
* Allow multiples in syste.propertis (decimals, tokens)
* registry.chain{Decimals, Token} returns array values
* Bump common
* AbstractInt format with first decimal/token
* Adjust ss58Format consistency
* u8 decimals/format
* cleanups
* More slight weidness
* Adjust all t u32
* Cleanup properties format from Codec
* Don't log full error
In `txwrapper` we can't always know if a payload is a signing payload or a signed tx so we first try one and then the other. When the former fails users get a scary-looking error. If upstream logs the error there's little we can do about it lest we [monkey patch `console.error`](https://github.com/paritytech/txwrapper-core/pull/22/files#diff-ea2d1c5845dd0e2fb9814e98a3464c2c63a43922983391e98fe9c20c328e979cR55) which is nasty af.
Hence this PR that removes the log here so that downstream can choose what to do with the error message.
* Add UnsafeOptions to let callers decide if they want errors logged or not
* Update packages/api-contract/src/util.ts
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
* Update packages/rpc-core/src/index.ts
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
* Update packages/rpc-core/src/index.ts
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
* Update packages/types/src/create/createType.ts
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
Co-authored-by: Jaco Greeff <jacogr@gmail.com>
* use queryStorageAt for multi storage queries
* fix lint
* e2e tests
* skip lints for api.spec.ts
* remove e2e test from PR
* do not decorate multi() if can not supported
* empty line
* update
Co-authored-by: Ian He <ian.he@centrality.ai>
* WIP on bounties derive.
* wip
* Some basic tests for derive bounties
* Simplify bounties derive and mocks
* Get bounties and descriptions
* Allow for empty bounties. Refactor tests.
* Move tests to test directory
* Attempt to remove duplication
* Sort imports
* Reorganize tests
* Change returned type
* Bump metadata (w/ AssetBalance, AssetDetails)
* Bluperint for new-style with salt as default
* Use TBalance
* Easier overrides
* Balance
* Build types
* Use logger in error/warning messages
* Update packages/types/src/codec/BTreeSet.ts
* Update expectation
* Some additional type tests
* resgirty.hash returns H256
* Additional override test
* Cleanup with meta registry
* Update packages/api-contract/src/MetaRegistry.ts
* Allow for Str type
* No .only
* Cleanups
* Registry references
* Cleanups, real registry
* Ordering
* Future-proof
* ContractRegistry always has own registry instance
* Hacky Bytes notation
* Revert Bytes (for now, keep it simple)
* Apply suggestions from code review
* Expand on found error
* Updated ABI definitions & parsing
* Run type generation
* Definitions (should be ok-ish)
* Cleanup names
* Allow aliasses on structs (JSON parsing)
* Cleanup json mapping passing
* s/types/lookup/
* Parsing as per current output
* InkSelector
* MtRegistryIndex
* String lookup tests
* Remove serd ovverride comments (it works as-is)
* inkRegistry tests
* Extract primitive types
* s/ty/id/
* Start of parsing into types (actually to be TypeDef)
* Parsing
* stringify struct fields
* Small cleanups
* Add type index to project lookup
* Prefix with index
* Fix interface generation
* Latest contract metadata (#2118)
* Add new (provisional) incrementer contract metadata
* Update and regenerate type definitions
* WIP: generate new format scale-info types
* WIP: implementing variants
* Implement variants
* Fix up type resolution
* Fix registry spec tests
* Fix lints and some tests
* Fix inkTypes tests
* Fix some lints
* Make imports same line like original
* Comment out (temporarily) sanitize import to make CI pass
* Sanitize
* Remove indices
* Remove index
* Adjust ContractAbi interface (empty rpc)
* linting
* Pull in Andrew's changes
* Cleanups
* Some more cleanups
* Update with v3 contracts
* Adjust with actual types
* Regenerate
* Update ABI parsing (#2695)
* Adjust ABI code
* Cleanup
* Merge non-code
* Type naming
* Simplify Base
* Rename 1
* rename 2
* Rename 3
* Simplify
* Add index to AbiMessage
* Pass actual message or index for call
* Rename param
* Simplify
* Expose call & exec
* s/call/read/
* Cleanup asserts
* AccountId as per spec
* displayName is path
* Update definitions
* Flatten ABIType into TypeDef
* Rewrite
* Fix tests
* Updates
Co-authored-by: Andrew Jones <ascjones@gmail.com>
Upgrade priority: Medium. Required for the next v0.9.0 Polkadot/Kusama chain upgrades where parachains are used.
- **Breaking change** The previously deprecated contracts interfaces, has been removed. Update to `<myContract>.query.*`, `<myContract>.tx.*` and `<myCode>.tx.*` interfaces as per the previous code usage hints.
- **Important** By default the `isPedantic` mode is now switched on for storage queries. This means that the API will fail on any types where the input/output decoding doesn't match 100%
Changes:
- Re-add isPedantic check on storage decoding
-`ConsensusEngineId` now implements `[u8;4]` (mapping closer to Rust source)
- Additional Xcm types
- Adjust parachain types
- Remove error logging on createType (details passed in error)
- Adjust `ContractInfo` type as per latest Substrate
- Adjust `DigestItem` type as per latest Substrate
- Adjust re-encoding of `BitVec` based on decoded length
Upgrade priority: Low. Recommended if you use the API to sync the full chain, most notably Polkadot.
Contributed:
- Re-add unused historical `SudoBalances` to `ProxyType` (Thanks to https://github.com/emostov)
## 4.0.2 Mar 8, 2021
Upgrade priority: High. Required if you are using 4.0.1 in a Node.js environment.
Changes:
- Fix import from `@polkadot/x-rxjs` in Node environments (From common)
- Add correct types for `Phase` is new validator elections module
## 4.0.1 Mar 7, 2021
Upgrade priority: Low. Recommended for users wanting to keep updated with chain changes.
**Important** In the 4.0 version the default package type has been changed to ESM modules by default. This should not affect usage, however since the output formats changed, a new major version is required.
Contributed:
- Expose `unknownTypes` on the registry interface (Thanks to https://github.com/ii-ii-ii)
Changes:
- Build to ESM by default (with cjs versions via export map)
- Enum `.toSON()` now encodes all keys as `camelCase` (aligning with the output from Substrate)
- Add `createdAtHash?: Hash` to `Codec` interface (filled-in by storage retrievals)
- Expose the source hash as `wamHash` on Abi parsed instances
- Use `parentHash` when creating mortal era (handles frequent forks better)
- Add `AccountInfoWithTripleRefCount` to cater for latest Substrate
- Add upgrade block for Westend 49
## 3.11.1 Feb 28, 2021
Upgrade priority: Low. Recommended for users wanting to keep updated with chain changes.
Contributed:
- Clean Websocket states on disconnects (Thanks to https://github.com/ianhe8x)
- Support for C-like indexed enums (Thanks to https://github.com/xlc)
Changes:
- Adjust council derives to cater for current-generation candidate mapping
- Allow for override of codec hasher (& output type)
- Adjust submittables to submit hex-encoded addresses to queries
- Adjust initialization to always retrieve tx version from Metadata only
- Update election types as per latest Substrate
- Add types for the new gilt module
- Upgrade to the latest Substrate metadata
- Adjust package detection to check for local monorepo dependencies
- Ensure that metadata `.toJSON()` does apply type aliasses
## 3.10.2 Feb 23, 2021
Upgrade priority: Medium. Recommended for users of chains where `MultiAddress` is in-use and blocks are decoded.
Changes:
- Fix decoding for `MultiAddress` enum where non-`AccountId` variable-lengths are provided as part of a stream
- Added known Polkadot 28 upgrade block
- Update for latest Substrate contracts `Schedule` types
## 3.10.1 Feb 22, 2021
Upgrade priority: Low.
Changes:
- Adjust ConsumedWeight types to align with Rust module code
- Check for connection status in subscription unsubscribe
- Adjust staking reward derives ordering for better performance
- Adapt detection imports to remove `.json` dependencies (Better behavior using Node.js with ESM)
## 3.9.3 Feb 16, 2021
Upgrade priority: Low. Recommended for parachain builders since it contains the updated parachain types.
- Add alias for `system_unstable_networkState` RPC
## 3.9.1 Feb 14, 2021
Upgrade priority: Low.
- **Important** The `Result<T, E>` has been updated in the generation and the base types to follow the Rust version 100%. This means `{as, is}Error` is now available as `{as, is}Err` on the `Result` type. The older versions can still be used, but the `*Error` interfaces are now marked as deprecated.
Changes:
- Adjust `Result<T, E>` interface to be 100% compatible with the Rust version
- Add the `2028` upgrade to the known upgrades (optimizing certain `.at` queries)
- Adjust council derives to cater for latest Substrate & Polkadot
- Adjust Rococo know type definitions to cater for the latest update
- Update types for latest Polkadot/Substrate
- Add generic arguments for TypeScript users to `.entries/.keys` to deal with the key typings
## 3.8.1 Feb 7, 2021
Upgrade priority: Low. Recommended for users of the latest Substrate master, especially using contracts.
- **Important** The `api-contract``Code` now supports deploying the code and a contract in on operation. This aligns with the latest Substrate where code cannot be uploaded with a contract. The `createBlueprint` is therefore deprecated, use `code.tx.<constructor>(...)` to deploy code. (Compatible with both old and new versions of Substrate)
Contributed:
- Add support for latest Frontier RPCs (Thanks to https://github.com/jnaviask)
- Fix user-supplied signed extensions type signature (Thanks to https://github.com/ntduan)
Changes:
- Expand `api-contract` to allow for `Code` to deploy contract alongside code. `createBlueprint` is now deprecated, replaced by `createContract` or the preferred `code.tx.<constructor>`, which uploads and deploys the code in one operation. This aligns with the current Substrate master contracts implementation.
- Allow for signed extensions to be supplied inside type bundles
- Ensure that the auto-connect state is checked on auto-connections (respecting disconnect)
- Added `CancelProxy` to `ProxyTypes on Polkadot, Kusama & Westend
- Adjusted the `Keys` type for the 28 runtime on Kusama, Polkadot & Westend
## 3.7.1 Feb 1, 2021
Upgrade priority: Low. However recommended for current Substrate master, Polkadot and Rococo users and those wishing to support the upcoming Polkadot 28 runtime with the new `MultiAddress`.
- **Breaking change** As indicated in the 3.5.1 release notes, the `Address`/`LookupSource` defaults have now been adjusted for `MultiAddress`. If your chain does not use these types, explicitly add the correct `Address`/`LookupSource` types. This new extensible format is mean to cater for all address types into the future, removing a lot of discrepancies between chains.
Contributed:
- Extraction of the block author on Moonbeam (Thanks to https://github.com/joelamouche)
- Cleanup logs with HTTP providers, no subs (Thanks to https://github.com/Tbaut)
Changes:
- Allow `.slice` operator on the `Vec` type
- Apply `MultiAddress` as a default
- Adds support for the upcoming Polkadot 28 and Kusama 2028 runtimes
- Add checkpoint for Kusama 2027 upgrade
- Update all parachain types (as per latest Rococo)
- Correctly use relay blockNumber in parachain validation data
- remove information log for capabilities detection (creates confusion)
- Remove explicit references to `global`, use the `x-global` detection
- Remove explicit `module` in `package.json` (exports map available)
## 3.6.1 Jan 24, 2020
Upgrade priority: Medium if not already on at least 3.3.1. The next upgrade of Kusama/Polkadot requires it.
- **Breaking change** To support chains with multiple tokens, such as bridges, the `ChainProperties` type now returns an array of tokens and decimals (instead of singular values) in the `token{Decimals, Symbol}` getters. Additionally, this means that the `registry` interfaces has been changes, to `registry.chainDecimals: number[]` and `registry.chainTokens: string[]`. Where used the `[0]` index will return the first value if only interested in a single, for a straight conversion.
Changes:
- Allow for the detection of on-chain capabilities as available (e.g. `AccountData`, `ValidatorPrefs`)
- Cater for multiple tokens and decimals in the chain the chain `system.properties` (as per the chain specification)
- Add a `instances: { [key]: [module1, module2] }` definition in teh bundle types, allowing for multiple instances (e.g. Balances)
- Adjust the `api-derive` for balances to retrieve values via `instances` as well as across multiple modules
- Ensure all types are registered for all metadata typegen steps
- Add `rpc.payment.queryFeeDetails` RPC endpoint
- Update types & metadata to latest Substrate
- Move the `@polkadot/x-rxjs` package into the common repo
- Allow doc generation for errors/events (markdown outputs)
## 3.5.1 Jan 18, 2020
Upgrade priority: Low. Recommended for parachain developers.
- **Important** The default for Substrate on the Address types are `MultiAddress`. It is recommended that chains add explicit definitions for `Address` and `LookupSource` in their types, instead of relying on the API-defaults. A future update will swap the API defaults to align with Substrate.
- **Important** Like the above changes in Substrate, the `AccountInfo` structure has also changed. It is recommended that chain developers explicitly add `AccountInfo: 'AccountInfoWithRefCount'` for the version with `refCount` on and `AccountInfoWithProviders` for the latest Substrate version. As per the above, the API defaults will be changed to align with Substrate.
Contributed:
- Apply correct TypeScript type for `toBigInt()` (Thanks to https://github.com/ianhe8x)
- Expand type definitions for storage key tuples (Thanks to https://github.com/monitz87)
- Adjust bounty derive to cater for non-council chains (Thanks to https://github.com/ekowalsk)
Changes:
- Remove recursion in vector/struct U8a stream decoding
- Availability of staking made optional in session length calcs (era does require it)
- Updates to parachain types, ensuring it has coverage for all the latest
- Update all Rococo types to the latest (session keys, session reports, parachain indexes)
- Update known upgrade checkpoints fo WestEnd
- Add types of the lottery module in Substrate
- Add and extend types for the crowdloan module in Polkadot
- Adjust node-template to default to `MultiAddress` on specVersion >= 100
## 3.4.1 Jan 11, 2020
Upgrade priority: Low. Fixes for parachain types, `.entries()` (with no values) and `event.is(...)` checks, users of these interfaces will have benefit.
- **Breaking change** The `derive.chain.{getBlock, subscribeNewBlocks}` now return `SignedBlockExtended`, all with the actual extrinsics and events mapped. Users of the latter interface should take note.
Contributed:
- Fix `SessionKeys{6-9}` definitions (Thanks to https://github.com/icodezjb)
- Support `Vec<(a, b)>` in enums (Thanks to https://github.com/monitz87)
- Add motions to bounty derive (Thanks to https://github.com/ekowalsk)
Changes:
-`derive.chain.getBlock()` now maps events to extrinsics via `.extrinsics` getter
- Ensure dispatchInfo is extracted on failed extrinsics (`getBlock` derive)
- Allow specification of additional signed extrinsic via API options
- Add missing parachain types, `ParaGenesisArgs`
- Correct `EthTransaction` type (as per the correct cargo crate)
- Update with latest contract types for Substrate master
- Update alias mapping for asset palette (including Substrate starting defaults)
- Allow `.entries()` call where 0 keys are present
- Fix `.is` on events not checking the correct index
- Construction of `i*` types ow correctly checks for max positive/negative
## 3.3.1 Jan 4, 2021
Upgrade priority: Low. Recommended for users of frontier evm module with additional types.
Contributed:
- Expand bounty derives (Thanks to https://github.com/ekowalsk)
- Adjust known-types (Thanks to https://github.com/mikiquantum)
Changes:
- Parallelize the API-init RPC calls for faster overall startup
- Add `ExitReason` types for the frontier evm module
- Adjust checks for indexed/non-indexed module checks (metadata decoration)
- Apply module aliases on constants (aligning with events, extrinsics)
- Allow for use of `system.ss58Prefix` as exposed (current Substrate master)
- Correct use of api-contract `blockWeights.maxBlock` in estimation
- Build metadata docs & interfaces with section aliases
- Update to latest Substrate master metadata in tests
## 3.2.1 Dec 27, 2020
Upgrade priority: Low. Recommended for users of parachains.
Contributed:
- Adjust metadata `.asV12` type signature (Thanks to https://github.com/yjhmelody)
- Support `AccountInfo` with new provider/consumer refCount structure
- Additional Cumulus parachain types
- Consistently format number JSON based on bitLength
- Cleanup metadata -> api dependencies
- Update `@polkadot/util` to 5.2.1
## 3.1.1 Dec 20, 2020
Upgrade priority: Low. Recommended for users of parachains.
Contributed:
- Additional parachain types (Thanks to https://github.com/joelamouche)
- Support for multi queries with `HttpProvider` (Thanks to https://github.com/ianhe8x)
- Configurable error logging with `createTypeUnsafe` (Thanks to https://github.com/dvdplm)
Changes:
- Adjust core type creation, removing storage duplication
- Update parachain types to support Rococo v1
- Adjust bounties derive to cater for new Substrate namespaces (& move to bounties)
- Mark `detectPackage` as known side-effect
- Add `detectPackage` to `@polkadot/metadata` (a number of requests on this)
- Adjust x-rxjs wrapper to expose all methods, incl. Node.js esm fixes
- Update to latest Substrate static metadata
- Update `@polkadot/util` to 5.1.1
## 3.0.1 Dec 14, 2020
Upgrade priority: Low. Recommended for the next Kusama/Polkadot upgrades due to additional types and those following chains following Substrate master closely.
**Important** While this package contains no external interface changes, it now compiles and ships both cjs and esm modules. This means that modern bundlers will have more information for tree-shaking available. Additionally when using Node with `.mjs` extensions, the esm version imports will be used on recent Node versions. Adding an export map, as here, may have some impacts so a major semver bump is advised. There may be (small) dragons hiding in the dark corners...
Contributed:
- Injection of derives via typesBundle (Thanks to https://github.com/pr0fedt)
- Added derives for bounties (Thanks to https://github.com/krzysztof-jelski)
Changes:
- Build and expose both cjs and esm via exports map
- Inject RPC definitions for typesBundle, allowing per-spec configuration
- Added `query.<section>.<method>.sizeAt(hash, [...params])` for all storage
- Adjust staking derives to be more performant (flags indicate which query values to retrieve)
- Add account derive to cater for the availability of identities
- Use `import type` in all cases
## 2.9.1 Nov 30, 2020
Upgrade priority: Low. No major changes when on at least 2.8.2. Users encouraged to upgrade to at least that patch.
- **Breaking change** The API will now not attempt to queue calls made while not connected and send on connection. Rather when making a call and the RPC node is not connected, an error will be thrown.
Contributed:
- Add typegen capability for custom RPCs (Thanks to https://github.com/holygits)
Changes:
- Remove rpc-core send queue, only allow sends while connected
- Adjust staking derive for `electedInfo` to contain details of current validators
- Extract identity-only derive from `accounts.info` for simpler reusability
- Add types for Substrate master node (to allow for consistent swapping to `MultiAddress`)
- Adjust `Bytes` with `.slice` to be consistent for `Uint8array` extensions (already released in 2.8.2 as a bugfix)
## 2.8.1 Nov 23, 2020
Upgrade priority: Low. Recommended if using Substrate master with new `MultiAddress`.
Contributed:
- Export `derive.chain.getBlock` (Thanks to https://github.com/lovesh)
Changes:
- Expand `MultiAddress` construction with multi type detection
- Rename `GenericLookupSource` to `IndicesLookupSource` (internal use)
- Cleanup list retrievals with `Raw` data results for undecodable entries
- Export actual version via `RegistryMetadata`
- Dedupe bn.js (one version shared between dependencies)
## 2.7.1 Nov 16, 2020
Upgrade priority: Medium. Recommended for users of Polkadot/Kusama and api-contract users.
Changes:
- Allow for `ExtrinsicSignature` overrides (defaults to `MultiSignature`)
- Update api-contract `Blueprint` to allow for optional salt (auto if not provided)
- Support for ink! `.contract` files (in addition to ABI `.json`)
- Fix contract event decoding with pass-through of raw `Bytes`
- Fix support for enum encoding in api-contract
- Support new contract `Schedule` type as per Substrate
Upgrade priority: Low. Should be done alongside an update to `@polkadot/util` to 4.0
Changes:
- Adjust auto-gas to contract RPC call to 5 * 10 ^ 12 (align with Rust)
- Adjust derive `AccountId` check to take Ethereum-compatible chains into account
- Fallback for chains with invalid council proposal data in derives
- Bump static v12 Metadata (tests) to latest Substrate version
- Bump `@polkadot/{util,util-crypto}` to 4.0 (optimized WASM layers)
## 2.5.1 Nov 2, 2020
Upgrade priority: Low. Recommended for `api-contract` developers.
- **Breaking change** Substrate changed the `ContractExecResult` from `api.rpc.contracts.call`. The API does have pass-through support for both old and new variants via the `Contract` interface, however it means the structure has changed to accommodate the new Substrate structure. Refer to the [docs for the latest interface](https://polkadot.js.org/docs/api-contract/start/contract.read) (including `isSuccess/isError` -> `isOk/isErr`, and the availability of the `gasConsumed`)
Contributed:
- Dedup similar types on generation (Thanks to https://github.com/monitz87)
Changes:
-`Contract` execution will now return contract events decoded in the result
- Add `.dryRun` on extrinsics (alongside `.paymentInfo` usage)
- Add `system_syncState` and `syncstate_genSyncSpec` RPCs
- Enhance error reporting, `Call` indicates explicit call as found
- Adjust internal metadata decoration and use as exposed from `@types/metadata`
- Expand Rococo known types to cater for v1 (specVersion 10)
-`registry.hash` now returns an `H256` object (as opposed to raw Uint8Array)
- Use utility logger in all relevant error messages (consistency in logging)
- Add `derive.council.proposal(<hash>)` for retrieval of a single (expanded) proposal
- Correctly and transparently format type generation types (allowing for nested variants)
## 2.4.1 Oct 26, 2020
Upgrade priority: Low. No breaking changes, however it does move `api-contract` forward with additional features.
Contributed:
- Add support for both `{i,u}256` types on contracts (Thanks to https://github.com/seanyoung)
Changes:
- Add `.keysAt` & `.entriesAt` to query maps at a specific blockHash
- Adjust ordering of type injection, any `types: { ... }` definitions not have precedence
- Correctly format Tuples in both RPC and const definitions as part of type generation
- Add node-template to known types (tracking inside API), remove warnings for the spec
- Add initial implementation for new Substrate `MultiAddress` type
- Add `api.derive.chain.subscribeNewBlocks` for full block retrievals
- Contracts identifiers to `.{exec, read}('name', ...)` now matches on both snake_case and camelCase (consistency)
- Cleanup contracts serialization for messages to allow both to and from
- Add deserialization of contract events against the ABI
- Adjust contracts metadata parsing to be future-proof with type retrievals
- Add tests for Solang into contracts, re-organize layout per type
## 2.3.1 Oct 19, 2020
Upgrade priority: Low. Recommended for `api-contract` developers and those using large messages via Node.js WS.
Contributed:
- Adjust frame size for Node.js WebSockets (Thanks to https://github.com/mnaamani)
- Update warnings to reflect new docs URLs (Thanks to https://github.com/aphelionz)
Changes:
- Expose `dispatch{Error, Info}` on all `.tx` results (less boilerplate on info checks)
- Add missing primitive types inside contracts type parsing
- Adjust api-contract to expose `Contract.{query, tx}.<message>` and `Blueprint.tx.<constructor>`
- Rework contracts registry to be generic to all scale-info definitions
- Allow for auto-max weight on contract read/exec (useful in estimation)
- Fix memoization where `BigInt` params are passed
## 2.2.1 Oct 12, 2020
Upgrade priority: Low.
- **Breaking change** `@polkadot/api-contract` now only supports ink! 3.0-rc1 and later formats. Users of ink! 2.1 are recommended to stay on an older version until upgraded.
Contributed:
- Add latest Ink! types (Thanks to https://github.com/ascjones & https://github.com/kwingram25)
- Add base for new contract metadata parsing (Thanks to https://github.com/ascjones & https://github.com/kwingram25)
Changes:
- Introduce `OriginCaller` type (& apply to scheduler types)
- Adjust `ContractInfo` type for latest Substrate (contracts)
- Adjust `Schedule` type for latest Substrate (contracts)
- Allow snake_case to be handled transparently in structs
- Full new api-contract developer interfaces (Code, Blueprint, Contract)
- Rework Abi & Abi Registry use & parse (based on contributed) for efficiency & non-global clobber
- Allow `null` input on `Text` values in addition to existing `undefined`
- Remove all documentation after move to https://github.com/polkadot-js/docs repo
- Adjust type encoding from TypeDef, s/encodeType/encodeTypeDef/
## 2.1.1 Oct 5, 2020
Upgrade priority: Low.
Contributed:
- Remove unused documentation link (Thanks to https://github.com/roccomuso)
Changes:
- Adjust RPC error formatting with string cleanups and a larger allowed range
- Apply limit protection on `Text` & `Bytes`, protecting against OOM on erroneous decoding
- Add `derive.staking.validatorsFrom` to determine validators nominated and own validators
- Cleanup document generation without (currently unused) summary links
- Rename static TRANSACTION_VERSION to EXTRINSIC_VERSION (Substrate alignment)
- Bump Substrate metadata (tests, doc generation)
## 2.0.1 Sep 28, 2020
Upgrade priority: Medium. Required for all teams building on Substrate 2.0 for full compatibility.
This library provides a clean wrapper around all the methods exposed by a Polkadot/Substrate network client and defines all the types exposed by a node. For complete documentation around the classes, interfaces and their use, visit the [documentation portal](https://polkadot.js.org/api/).
This library provides a clean wrapper around all the methods exposed by a Polkadot/Substrate network client and defines all the types exposed by a node. For complete documentation around the classes, interfaces and their use, visit the [documentation portal](https://polkadot.js.org/docs/api/).
If you are an existing user, please be sure to track the [CHANGELOG](CHANGELOG.md) and [UPGRADING](UPGRADING.md) guides when changing versions.
## tutorials
Looking for tutorials to get started? Look at [examples](https://polkadot.js.org/api/examples/promise/) for guides on how to use the API to make queries and submit transactions.
Looking for tutorials to get started? Look at [examples](https://polkadot.js.org/docs/api/examples/promise/) for guides on how to use the API to make queries and submit transactions.
## overview
@@ -21,27 +21,10 @@ The API is split up into a number of internal packages -
- [@polkadot/api](packages/api/) The API library, providing both Promise and RxJS Observable-based interfaces. This is the main user-facing entry point.
- [@polkadot/api-derive](packages/api-derive/) Derived results that are injected into the API, allowing for combinations of various query results (only used internally and exposed on the Api instances via `api.derive.*`)
- [@polkadot/api-metadata](packages/api-metadata/) Base extrinsic, storage and constant injectors for injection
- [@polkadot/rpc-core](packages/rpc-core/) Wrapper around all [JSON-RPC methods](https://polkadot.js.org/api/substrate/rpc.html) exposed by a Polkadot network client
- [@polkadot/metadata](packages/metadata/) Base extrinsic, storage and constant injectors for injection
- [@polkadot/rpc-core](packages/rpc-core/) Wrapper around all [JSON-RPC methods](https://polkadot.js.org/docs/substrate/rpc) exposed by a Polkadot network client
- [@polkadot/rpc-provider](packages/rpc-provider/) Providers for connecting to nodes, including WebSockets and Http
Type definitions for interfaces as exposed by Polkadot & Substrate clients -
- [@polkadot/jsonrpc](packages/jsonrpc/) Definitions for JSONRPC endpoints
- [@polkadot/types](packages/types/) Codecs for all Polkadot and Substrate primitives
## development
Contributions are welcome!
To start off, this repo (along with others in the [@polkadot](https://github.com/polkadot-js/) family) uses yarn workspaces to organise the code. As such, after cloning, its dependencies _should_ be installed via `yarn`, not via npm; the latter will result in broken dependencies.
To get started -
1. Clone the repo locally, via `git clone https://github.com/polkadot-js/api <optional local path>`
2. Ensure that you have a recent version of Node.js, for development purposes [Node 10](https://nodejs.org/en/) is recommended.
3. Ensure that you have a recent version of Yarn, for development purposes [Yarn >=1.10.1](https://yarnpkg.com/docs/install) is required.
4. Install the dependencies by running `yarn`
5. Build the everything via `yarn run build`
6. You can also launch the API Docs, via `yarn vuepress dev docs`
7. Access the docs via [http://localhost:8080](http://localhost:8080)
# Docker compose file to run Polkadot-JS API e2e test files on supported versions of Polkadot and Substrate
#
# Setup:
# Builds 5 containers with different supported versions of Substrate and Polkadot.
# Runs Polkadot-JS API Tests
#
# Before you can run this script, you need to install Docker and 'Docker Compose' on your machine.
# Please follow the steps described here (including the prerequisites): https://docs.docker.com/compose/install/
#
# Usage:
# 1. BUILD: Run `docker-compose pull && docker-compose up -d` to pull the latest docker imaged and run docker-compose in detached mode. This will run the substrate and polkadot containers in the background.
# 2. INFO: Run `docker ps` to get a list of Docker containers running in the background including their mapped ports on localhost
# 3. TEST: Run `docker-compose logs -f js-api-tests` to run the API tests and print the logs
# 4. QUIT: Run `docker-compose down` to stop and remove all running containers.
#
# Provided Endpoints for localhost:
# - Substrate Master: ws://127.0.0.1:9945/
# - Substrate 1.0: ws://127.0.0.1:9946/
# - Substrate 2.0: ws://127.0.0.1:9947/
# - Polkadot Master: ws://127.0.0.1:9948/
# - Polkadot Alexander: ws://127.0.0.1:9949/
#
# Find more Docker images of Substrate https://hub.docker.com/r/parity/substrate/tags
# Find more Docker images of Polkadot https://hub.docker.com/r/parity/polkadot/tags
The API provides application developers the ability to query a node and interact with the Polkadot or Substrate chains using Javascript. Here you will find documentation and examples to get you started.
::: tip Getting started & Examples
[Jump right in](/start/) and get an overview on using the API in your projects, from installation all the way through to making it do magic. Have things working and want tips? The [cookbook](/cookbook/) provides some tips and tricks. Getting started and want some full examples? [The ApiPromise examples](/examples/promise/) provide some basic examples.
:::
## The Polkadot Project
You can read more about the Polkadot Network at [https://polkadot.network/](https://polkadot.network/) and more about the polkadot-js projects at [https://polkadot.js.org](https://polkadot.js.org)
This documentation is generated from [https://github.com/polkadot-js/api](https://github.com/polkadot-js/api)
## Contributing
Contribution to the Polkadot JS API are more than welcome. You can [report issues](https://github.com/polkadot-js/api/issues/new) and [log feature requests](https://github.com/polkadot-js/api/issues/new).
The cookbook hosts small code snippets in a question-answer format. It does not walk you through the whole setup, like the [basic examples](../examples/), but rather aims to answer some questions around specific uses. It also does not replace the [getting started FAQ](../start/FAQ.md), rather this is focussed explicitly on code samples, instead of general trouble-shooting for common mishaps.
These questions are added as they do come up and the hope is that the snippets here is will be useful to others, instead of just the original person who asked on a specific use-case. As of today, it is only making a start and not fully comprehensive yet - check back early, check back often.
## Sections
The following cookbook sections are available -
- [Blocks](blocks.md) - Snippets around working with blocks and headers
- [Storage](storage.md) - Snippets for working with storage
- [Transactions](tx.md) - Snippets for working with transactions
... more to come.
## Contribute
And as always, if you have an addition to make, or a question to ask any [any PRs](https://github.com/polkadot-js/api/tree/master/docs) or [issues](https://github.com/polkadot-js/api/issues) are appreciated. The initial content was generate from exactly such questions, either in Riot chat or as submitted as issues.
The building blocks for each blockchain. As such there are a number of examples for working with blocks and headers, that could be useful.
## How do I retrieve the header/extrinsic hash from blocks?
A block hash refers to the hash over the header, the extrinsic hash refers to the hash of the encoded extrinsic. Since all objects returned by the API implements the `.hash => Hash` getter, we can simply use this to view the actual hash.
The block author is encoded inside the consensus logs for the block. To extract, you need to decode the log (which the API does do) and then map the index of the validator to the list of session validators. This extraction is however available on the api derive for new head subscriptions, which returns an extended header with the author populated (assuming that the digest logs are known).
```js
// subscribe to all new headers (with extended info)
The transactions are included in a signed block as part of the extrinsics - some of these will be unsigned and generated by the block author and some of these may be submitted from external sources and be signed. (Some palettes do use unsigned transactions, so signed/unsigned is not an indication of origin). To retrieve the block and display the transaction information, we can do the following -
```js
// no blockHash is specified, so we retrieve the latest
In the above `.toHuman()` is used to format into a human-readable representation. You can inspect/extract specific fields from the decoded extrinsic as required, for instance `ex.method.section` would return the pallete that executed this transaction.
Here you will find snippets for working with storage.
## How do I check for storage existence?
In the metadata, for each storage item a fallback is provided. This means that when an entry does not exist, the fallback (which is the default value for the type) will be provided. This means, that querying for a non-existent key (unless an option), will yield a value -
In the second case, the non-existent prefs returns the default/fallback value for the storage item. So in this case we don't know if the value is set to 0 or unset. Existence can be checked by using the storage size, which would be zero if nothing is stored.
## How do I use .entries()/.keys() on double maps?
As [explained elsewhere](../start/api.query.other.md#map-keys-entries) each map-type storage entry exposes the entries/keys helpers to retrieve the whole list. In the case of double maps, with the addition of a single argument, you can retrieve either all entries or a subset based on the first map key.
In both these cases, entries/keys operate the same way, `.entries()` retrieving `(StorageKey, Codec)[]` and `.keys()` retrieving `StorageKey[]`
```js
// Retrieves the entries for all slashes, in all eras (no arg)
A blockchain is no fun if you are not submitting transactions. Or at least if somebody is not submitting any. Here you will find some snippets for dealing with some common issues.
## How do I estimate the transaction fees?
In addition to the `signAndSend` helper on transactions, `.paymentInfo` (with the exact same parameters) are also exposed. Using the same sender, it applies a dummy signature to the transaction and then gets the fee estimation via RPC.
```js
// estimate the fees as RuntimeDispatchInfo, using the signer (either
// address or locked/unlocked keypair) (When overrides are applied, e.g
// nonce, the format would be `paymentInfo(sender, { nonce })`)
constinfo=awaitapi.tx.balances
.transfer(recipient,123)
.paymentInfo(sender);
// log relevant info, partialFee is Balance, estimated for current
console.log(`
class=${info.class.toString()},
weight=${info.weight.toString()},
partialFee=${info.partialFee.toHuman()}
`);
```
## How do I get the decoded enum for an ExtrinsicFailed event?
Assuming you are sending a tx via `.signAndSend`, the callback yields information around the tx pool status as well as any events when `isInBlock` or `isFinalized`. If an extrinsic fails via `system.ExtrinsicFailed` event, you can retrieve the error, if defined as an enum on a module.
```js
api.tx.balances
.transfer(recipient,123)
.signAndSend(sender,({status,events})=>{
if(status.isInBlock||status.isFinalized){
events
// find/filter for failed events
.filter(({section,method})=>
section==='system'&&
method==='ExtrinsicFailed'
)
// we know that data for system.ExtrinsicFailed is
// (DispatchError, DispatchInfo)
.forEach(({data:[error,info]})=>{
if(error.isModule){
// for module errors, we have the section indexed, lookup
For most runtime modules, transactions need to be signed and validation for this happens node-side. There are however modules that accepts unsigned extrinsics, an example would be the Polkadot/Kusama token claims (which is here used as an example).
```js
// construct the transaction, exactly as per normal
// send it without calling sign, pass callback with status/events
tx.send(({status})=>{
if(status.isInBlock){
console.log(`included in ${status.asInBlock}`);
}
});
```
The signing is indicated by the first byte in the transaction, so in this case we have called `.send` on it (no `.sign` or `.signAndSend`), so it will be sent using the unsigned state, without signature attached.
## How can I batch transactions?
Polkadot/Substrate provides a `utility.batch` method that can be used to send a number of transactions at once. These are then executed from a single sender (single nonce specified) in sequence. This is very useful in a number of cases, for instance if you wish to create a payout for a validator for multiple eras, you can use this method. Likewise, you can send a number of transfers at once. Or even batch different types of transactions.
```js
// construct a list of transactions we want to batch
consttxs=[
api.tx.balances.transfer(addrBob,12345),
api.tx.balances.transfer(addrEve,12345),
api.tx.staking.unbond(12345)
];
// construct the batch and send the transactions
api.tx.utility
.batch(txs)
.signAndSend(sender,({status})=>{
if(status.isInBlock){
console.log(`included in ${status.asInBlock}`);
}
});
```
## How do I take the pending tx pool into account in my nonce?
The `system.account` query will always contain the current state, i.e. it will reflect the nonce for the last known block. As such when sending multiple transactions in quick succession (see batching above), there may be transactions in the pool that has the same nonce that `signAndSend` would apply - this call doesn't do any magic, it simply reads the state for the nonce. Since we can specify options to the `signAndSend` operation, we can override the nonce, either by manually incrementing it or querying it via `rpc.system.accountNextIndex`.
```js
for(leti=0;i<10;i++){
// retrieve sender's next index/nonce, taking txs in the pool into account
In addition to querying the latest storage, you can make storage queries at a specific blockhash. Be aware that the node applies a pruning strategy and typically only keeps the last 256 blocks, unless run in archive mode.
This transactions shows you how to add a nonce and a valid length of blocks a transaction is valid for.
This is important because as an account drops below the exsistential limit (0.1 dots) it gets pruned from the state tree. If it is added back its nonce starts at 0 again and is now vulnerable to replay attacks.
Performs a chain upgrade using the `sudo` module. This may brick your chain, so use it as an educational sample. (use `substrate purge-chain --dev` to remove DB and recover).
This is a sample TypeScript project [with full source & config on GithHub](https://github.com/polkadot-js/api/tree/master/docs/examples/promise/90_typegen), that uses `@polkadot/typegen` to generate type definitions that can be used to decorate the `@polkadot/api`. It uses both types defined for the specific chain as well as the chain metadata to generate TypeScript interfaces. This means that interfaces such as `api.query.*`, `api.tx.*` and `api.consts.*` will be decorated based on chain-specific information, instead of an un-augmented catch-all definition.
**NOTE** This is built using the updates in the `1.4.0` api track and as such it uses the latest (at the time of writing) `@polkadot/api 1.4.0`. If you want to play on your own, it is also suggested that you use the `1.4+` series since some generation types have moved around internally, making it easier to augment.
## Packages
For the packages we need from the `@polkadot/*` we have added `@polkadot/api` (we want to do API stuff) and `@polkadot/typegen` (to generate the actual interfaces). So our scripts and dependencies inside `package.json` contain the following -
We will delve into the setup and running the scripts and what they do in a short bit, but as of now just notice that we are running the scripts via `ts-node`. Since we supply our definitions as `*.ts` files, this is important otherwise they will not be parsable. `build` will just run both the types and meta generators (in that order, so metadata can use the types) and we have a `lint` that can just check that everything is as it is meant to be.
## Metadata setup
The idea here is to use the actual chain metadata to generate the actual api augmented endpoints. The metadata we are adding here (in addition to the user types), is from the Edgeware Berlin testnet. So this is a real-world example of configuring the API for a specific substrate chain. For the metadata retrieval, we just ran a simple curl command to get it from the node -
And then add the full JSONPC output as received to the `edgeware.json` file as specified by the generation command. A trimmed version would look like -
The generator can also use a `wss://` as an `--endpoint` param as part of the generation, but in most cases you would want a static metadata to work from in development, hence we are actually adding it here.
## Types setup
The types are defined in the `src/interfaces` folder. While this repo contains a number of generated files in there as well, you basically only need to manually add the following -
- `src/interfaces/definitions.ts` - this just exports all the sub-folder definitions in one go
- `src/interfaces/<module>/definitions.ts` - type definitions for a specific module
This structure fully matches what is available in the `@polkadot/type/interfaces` folder, so the structure is setup based on the convention used in the `@polkadot/types` library. The generating scripts will expect something matching this since the same underlying code is actually used inside `@polkadot/types` as well. The top-level `interfaces/` folder can be name anything, however the internal content structure need to match what is defined above.
For the top-level the definition file has the following contents -
```js
export { default as signaling } from './signaling/definitions';
export { default as treasuryRewards } from './treasuryRewards/definitions';
export { default as voting } from './voting/definitions';
```
As explained above, it really is just a re-export of the definitions, so they are all easily accessible to the outside, i.e. we will use this import inside our own code to use the definitions in API initialization. The generation scripts will load this file to determine which types it needs to import. By the `@polkadot/types` convention, match the export names with the folders (preferably your runtime module names), the generation scripts will use these names to find the correct folders to output the generated `types.ts` to.
For each of the folders, `signaling`, `treasuryRewards` and `voting` another `definitions.ts` file is contained within. Looking at the one from `signaling`, it contains this -
```js
export default {
types: {
ProposalRecord: {
index: 'u32',
author: 'AccountId',
stage: 'VoteStage',
transition_time: 'u32',
title: 'Text',
contents: 'Text',
vote_id: 'u64'
},
ProposalContents: 'Vec<u8>',
ProposalTitle: 'Vec<u8>'
}
}
```
Just the type definitions (the structure of which you should be familiar with), nested inside a `types: {...}` container. This allows us future extension points, i.e. there is some work to expose the custom RPC types alongside, so that would become another key on a per-module basis.
In the above, you will note that the `ProposalRecord` references a type for `voting`, i.e. `VoteStage`. The type generation and resolution will determine where the type comes from, and provide the required imports on generation.
Looking at the example in this repo, it also has `augment*`, `index.ts` and `types.ts` files in the interfaces folder. These are all generated, and will be re-generated when the generator is run - so all edits to these files will be lost. The only requirement for user-edits are the `definitions.ts` files.
## Generating
Now that both the metadata and types setup is completed, we just run the build command via `yarn build` and magically (assuming you didn't have the `augment*` and other generated files), these files will be added. When running this command, the console should display something like -
Now if we check the actual output against the source via `yarn lint`, we would see that valid output has been generated -
```
> yarn lint
$ tsc --noEmit --pretty
✨ Done in 2.28s.
```
## Peering at the output
We are ready to use all these generated types this after some TS config. If you take a look at the generated `src/signaling/types.ts`, you would see generated TS interfaces, such as -
```js
import { Struct } from '@polkadot/types/codec';
import { Bytes, Text, u32, u64 } from '@polkadot/types/primitive';
import { AccountId } from '@polkadot/types/interfaces/runtime';
import { VoteStage } from 'sample-polkadotjs-typegen/interfaces/voting';
As mentioned earlier, here you will notice the `import { VoteStage }`, the generator has determined that `voting` exports that interface and has added the required imports.
## TypeScript config
Now that we have files generated, it is time to make TypeScript aware of the types and add an explicit override into out `tsconfig.json`. After some changes, the paths in the config looks as follow (comments are in the actual config file here) -
Effectively what we do above is tell the TypeScript compiler to not use the built-in API augmentation, but rather to replace it with our version. This means that all types from these are injected not by the substrate-latest-master version, but rather with what we have defined above.
## Usage
For simple usage, we have added the `src/index.ts` file that show how the metadata and types actually decorate the API. In addition, we also have setup instructions included here.
```js
// We need to import the augmented definitions "somewhere" in our project, however since we have
// it in tsconfig as an override and the api/types has imports, it is not strictly required here.
// Because of the tsconfig override, we could import from '@polkadot/{api, types}/augment'
import './interfaces/augment-api';
import './interfaces/augment-types';
// all type stuff, the only one we are using here
import type { VoteRecord } from './interfaces';
// external imports
import { ApiPromise } from '@polkadot/api';
import { createType } from '@polkadot/types';
// our local stuff
import * as definitions from './interfaces/definitions';
async function main (): Promise<void> {
// extract all types from definitions - fast and dirty approach, flatted on 'types'
Here you will find a list of examples that takes you through the basics of connecting to a local node, retrieving data from the Node and chain and execute transactions on the chain. It uses the [[ApiPromise]] interface.
## Prerequisites
For the following examples, you need a local node. It is usually convenient testing with:
```
substrate --dev
```
## Running the examples
From each folder, run `yarn` to install the required dependencies and then run `yarn start` to execute the example against the running node.
Those accounts are easy to add if you don't have/see them. The seed of Alice's account is `//Alice` (via `keyring.addUri(...)`, dev seed implied) and the seed of Bob is... well you guess...
"description":"Example showing how to query storage",
"main":"index.js",
"author":"Stefie",
"license":"MIT",
"scripts":{
"clean":"rimraf node_modules",
"start":"node index.js"
},
"dependencies":{
"@polkadot/api":"*"
},
"devDependencies":{
"rimraf":"^2.6.2"
}
}
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Github Actions