diff --git a/.gitignore b/.gitignore index b512c09d..2c9a6b3e 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -node_modules \ No newline at end of file +node_modules +/docs/dist \ No newline at end of file diff --git a/docs/components/Tabs.tsx b/docs/components/Tabs.tsx index 2d1247bb..b02717a4 100644 --- a/docs/components/Tabs.tsx +++ b/docs/components/Tabs.tsx @@ -15,6 +15,7 @@ export const Root = ({ {Object.entries(options).map(([value, label]) => ( diff --git a/docs/pages/getting-started.mdx b/docs/pages/getting-started.mdx index c335960b..df1a3f5c 100644 --- a/docs/pages/getting-started.mdx +++ b/docs/pages/getting-started.mdx @@ -83,7 +83,7 @@ Now you can create a PolkadotClient with that provider and start interacting wit ```ts // [!include ~/snippets/gettingStarted.ts:import] import { getScProvider } from "papee/sc-provider"; - import { createScClient } from "@substrate/connect"; + import { WellKnownChain, createScClient } from "@substrate/connect"; const scProvider = getScProvider(createScClient()); diff --git a/docs/pages/types.mdx b/docs/pages/types.mdx new file mode 100644 index 00000000..13375cc9 --- /dev/null +++ b/docs/pages/types.mdx @@ -0,0 +1,107 @@ +# Types + +All the types defined in the metadata of a chain are anonymous: They represent the structure of the data, down to the primitive types. + +Polkadot-API has some types defined that make it easier working with chain data. + +## SS58String + +Binary values tagged as a accounts are abstracted as `SS58String`. The type `SS58String` exported by Polkadot-API is an alias of `string`, but it's indicative that the string that it expects is an SS58-formatted string. The value will be encoded to the public address in binary. + +When PolkadotAPI receives an `SS58String` as a parameter, it can be in any valid format. But the `SS58String` returned from any of the methods will always be in the format declared by the chain's metadata. + +```ts +const dotApi = client.getTypedApi(dot); + +const [proxies, deposit] = await dotApi.query.Proxy.Proxies.getValue( + // HDX format (for demo purposes that it accepts any SS58 string, regardless of the chain) + "7LE64AxmGixNsxFs1rdsDkER5nuuQ28MbrSS7JtHwRmdcdam" +); + +console.log(proxies[0].delegate); +// "12R1XCdgkHysv8Y4ntiXguo4eUYHXjQTmfRjL8FbmezsG71j", which is polkadot's format +``` + +## HexString + +Another alias of `string`, but indicates that the value is a valid hexadecimal string. It accepts the string with or without the `0x` prefix, but `HexString` returned from methods always have `0x`. + + +## Enum + + +## Binary + +Any array of u8's is represented as Binary. This is a utility type that has a few functions to easily create binary data: + +```ts +Binary.fromBytes(new Uint8Array()) +Binary.fromHex("0b187a23c4f65d86c9a324b56f7e81aa") +const binary = Binary.fromText("Text that will be turned into binary") + +binary.asBytes(); // Uint8Array +binary.asHex(); // "0x5465787420746861742077696c6c206265207475726e656420696e746f2062696e617279" +binary.asText(); // "Text that will be turned into binary" + +``` + +## FixedSizeBinary<L> + +Same as `Binary`, but when the chain metadata specifies a length. The length is shown as a type parameter, for reference. + +## FixedSizeArray<L, T> + +When the metadata has a type that's an array of a specific length, that's also shown as a `FixedSizeArray<L, T>`, which is a superset of `Array<T>>`, except that it checks that the length must be `L`. + +## Interface types + +The types returned from any call are available through the top-level exports + +```ts +import { + dot, + DotQueries, + DotCalls, + DotConstants, + DotErrors, + DotEvents, +} from "@polkadot-api/descriptors"; + +// Storage queries +function processAccount(account: DotQueries["System"]["Account"]["Value"]) { + // ... +} +processAccount(await dotApi.query.System.Account.getValue("SS58Account")); + +// Constants +function formatSS58Account( + value: DotConstants["System"]["SS58Prefix"], + account: Uint8Array +) { + // ... +} +formatSS58Account(await dotApi.constants.System.SS58Prefix(), new Uint8Array()); + +// Transactions +function performTransfer( + transfer: DotCalls["Balances"]["transfer_allow_death"] +) { + return dotApi.tx.Balances.transfer_allow_death(transfer).signAndSubmit( + signer + ); +} +performTransfer({ + dest: MultiAddress.Id("SS58Account"), + value: 100n, +}); + +// Events +function reactToNewAccount(event: DotEvents['System']['NewAccount']) { + // ... +} + +// Errors +function logError(error: DotErrors['System']['InvalidSpecName']) { + // ... +} +``` diff --git a/docs/snippets/gettingStarted.ts b/docs/snippets/gettingStarted.ts index 27168a76..bcf13f7d 100644 --- a/docs/snippets/gettingStarted.ts +++ b/docs/snippets/gettingStarted.ts @@ -1,7 +1,7 @@ // [!region import] // `dot` is the name we gave to `npx papi add` import { dot } from "papee/descriptors"; -import { WellKnownChain, createClient } from "papee"; +import { createClient } from "papee"; // [!endregion import] // [!region usage] diff --git a/vocs.config.tsx b/vocs.config.tsx index b668565e..bfd09c2e 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -16,6 +16,10 @@ export default defineConfig({ text: "Codegen", link: "/codegen", }, + { + text: "Types", + link: "/types", + }, { text: "Signers", link: "/signers",