feat: add new hook docs

docs/frontend/react/hooks/all-hooks.md

@@ -15,12 +15,17 @@ description: A list of all useink hooks
 
 * [useCall](/frontend/react/hooks/contracts/use-call) - call a contract and get the decoded result or an error.
 * [useCallSubscription](/frontend/react/hooks/contracts/use-call-subscription) - call a contract and get the decoded result or an error on each new block.
+* [useCodeHash](/frontend/react/hooks/contracts/use-code-hash) - validate code hash values. Can be used when deploying contracts from hash.
 * [useContract](/frontend/react/hooks/contracts/use-contract) - create a contract client instance containing metadata and the contract's address.
+* [useDeployer](/frontend/react/hooks/contracts/use-deployer) - deploy a contract from Wasm or a code hash on chain.
 * [useDryRun](/frontend/react/hooks/contracts/use-dry-run) - send a dry run of a transaction to check if it will succeed and to determine gas costs.
-* [useEvents](/frontend/react/hooks/contracts/use-events) - fetch the events for a contract from state. Optionally filter by event name.
 * [useEventSubscription](/frontend/react/hooks/contracts/use-event-subscription) - subscribe to a contract's emitted events.
-* [useTx](/frontend/react/hooks/contracts/use-tx) - sign and send a contract transaction and get the decoded result or an error.
+* [useEvents](/frontend/react/hooks/contracts/use-events) - fetch the events for a contract from state. Optionally filter by event name.
+* [useTxEvents](/frontend/react/hooks/contracts/use-tx-events) - collect the events emitted in a single transaction. Used internally.
+* [useMetadata](/frontend/react/hooks/contracts/use-metadata) - load and validate a metadata file or contract file. Get the ABI for use with other hooks.
+* [useSalter](/frontend/react/hooks/contracts/use-salter) - generate random salt hexidecimal values and validate them. Can be used with useDeployer.
 * [useTxPaymentInfo](/frontend/react/hooks/contracts/use-tx-payment-info) - send a dry run of a transaction and get the total payment information required.
+* [useTx](/frontend/react/hooks/contracts/use-tx) - sign and send a contract transaction and get the decoded result or an error.
 
 ## Wallets
 
@@ -33,13 +38,13 @@ description: A list of all useink hooks
 
 * [useApi](/frontend/react/hooks/substrate/use-api) - get the api client instance configured for a specific chain. This contains RPC information, and is used in many other hooks.
 * [useBalance](/frontend/react/hooks/substrate/use-balance) - get an account's balance for a given chain.
-* [useTransfer](/frontend/react/hooks/substrate/use-transfer) - transfer funds to another account.
 * [useBlockHeader](/frontend/react/hooks/substrate/use-block-header) - get block header information for a chain on each new block.
+* [useChainDecimals](/frontend/react/hooks/substrate/use-chain-decimals) - get the decimal count for a chain. e.g. `12`
 * [useTimestampDate](/frontend/react/hooks/substrate/use-timestamp-date) - get block date on each new block.
 * [useTimestampNow](/frontend/react/hooks/substrate/use-timestamp-now) - get block unix timestamp in milliseconds on each new block.
 * [useTimestampQuery](/frontend/react/hooks/substrate/use-timestamp-query) - get a function that can be used to query timestamp info for a chain.
 * [useTokenSymbol](/frontend/react/hooks/substrate/use-token-symbol) - get the native token's symbol. e.g. `ROC`
-* [useChainDecimals](/frontend/react/hooks/substrate/use-chain-decimals) - get the decimal count for a chain. e.g. `12`
+* [useTransfer](/frontend/react/hooks/substrate/use-transfer) - transfer funds to another account.
 
 ## Helpers
 

docs/frontend/react/hooks/contracts/use-code-hash.md

@@ -0,0 +1,47 @@
+---
+title: 'useCodeHash'
+description: 'A React hook for validating code hash values for contract code on chain.'
+---
+
+# useCodeHash
+
+A React hook for validating code hash values for contract code on chain.
+
+## Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```tsx
+import { useCodeHash } from 'useink'
+
+export const DeployPage: React.FC = () => {
+  const C = useCodeHash();
+
+  return (
+    <div>
+      <label htmlFor='codeHash'>Code Hash</label>
+      <input
+        name='codeHash'
+        value={C.codeHash}
+        onChange={(e) => C.set(e.target.value)}
+      />
+      {C.error && <p>{C.error}</p>}
+    </div>
+  )
+};
+```
+
+## Return Value
+
+```ts
+{
+  codeHash: string;
+  set: (hash: string) => void;
+  error?: CodeHashError;
+  resetState: () => void;
+}
+
+export enum CodeHashError {
+  InvalidHash = "Invalid code hash value."
+}
+```

docs/frontend/react/hooks/contracts/use-deployer.md

@@ -0,0 +1,55 @@
+---
+title: 'useDeployer'
+description: 'A React hook for deploying a contract from a Wasm blob or code hash.'
+---
+
+# useDeployer
+
+A React hook for deploying a contract from a Wasm blob or code hash.
+
+## Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```tsx
+import { useDeployer } from 'useink'
+
+export const DeployPage: React.FC = () => {
+  // Optionally pass in a ChainId to deploy to another chain. 
+  // e.g. `useDeployer('shibuya-testnet')`.
+  // ChainId must be configured in your UseInkProvider config props.
+  const D = useDeployer();
+  // The code to load metadata this is omitted from this example. See useMetata docs.
+  const M = useMetadata(); 
+
+  return (
+    <>
+      {D.isSubmitting && <p>Submitting...</p>}
+      {D.error && <p>{D.error}</p>}
+
+      <button onClick={D.dryRun(M.abi, 'new')}>Dry Run</button>
+      <button onClick={D.signAndSubmit(M.abi, 'new')}>Deploy</button>
+    </>
+  );
+};
+```
+
+## Return Value
+
+```ts
+{
+  dryRun: DeploySignAndSend<Promise<DeployTx | undefined>>;
+  signAndSend: DeploySignAndSend<Promise<void>>;
+  contractAddress: string | undefined;
+  status: TransactionStatus;
+  result: ContractSubmittableResult | undefined;
+  isSubmitting: boolean;
+  error: string | undefined;
+  resetState: () => void;
+  gasConsumed?: WeightV2;
+  gasRequired?: WeightV2;
+  storageDeposit?: StorageDeposit;
+  willBeSuccessful: boolean;
+  events: EventRecord[];
+}
+```

docs/frontend/react/hooks/contracts/use-metadata.md

@@ -0,0 +1,68 @@
+---
+title: 'useMetadata'
+description: 'A React hook for loading and validating contract metadata from a file.'
+---
+
+# useMetadata
+
+A React hook for loading and validating contract metadata from a file.
+
+## Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```tsx
+import { useMetadata } from 'useink'
+
+export const DeployPage: React.FC = () => {
+  // When requireWasm is set to true you must upload a full <name>.contract file containing a valid Wasm field.
+  // -- The file and Wasm blob will be validated on calling `set(file)`
+  // When requireWasm is set to false you must upload a <name>.json metadata file.
+  // -- The file will be validated on calling `set(file)`
+  const M = useMetadata({ requireWasm: true });
+
+  if (M.abi) {
+    return (
+      <>
+        <p>{M.formattedFileName}</p>
+        <button onClick={M.clear}>Reset State</button>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <MyDropzoneComponent
+        onDrop={(f: File[]) => M.set(f?.[0])}
+        cta='Upload a contract file. e.g. "flipper.contract"'
+      />
+
+      {M.error && <p>{M.error}</p>}
+    </>
+  );
+};
+
+
+```
+
+## Return Value
+
+```ts
+{
+  abi?: Abi;
+  source?: Record<string, unknown>;
+  name: string;
+  formattedFileName: string;
+  set: (file: File) => void;
+  clear: () => void;
+  error?: MetadataError;
+}
+
+// Errors are exposed as enums for your convenience. 
+// If you are using i18n you can check for one of these types and translate accordingly.
+export enum MetadataError {
+  InvalidFile = 'Invalid file.',
+  EmptyWasm = 'Wasm field not found.',
+  InvalidWasm = 'Invalid Wasm field.',
+}
+```

docs/frontend/react/hooks/contracts/use-salter.md

@@ -0,0 +1,55 @@
+---
+title: 'useSalter'
+description: 'A React hook for generating random salt hex values and validating them.'
+---
+
+# useSalter
+
+A React hook for generating random salt hex values and validating them.
+
+## Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```tsx
+import { useSalter } from 'useink'
+
+export const DeployPage: React.FC = () => {
+  const S = useSalter();
+
+  return (
+    <div>
+      <label htmlFor='salt'>Salt</label>
+      <input
+        value={S.salt}
+        onChange={(e) => S.set(e.target.value)}
+      />
+
+      {S.error && <p>{S.error}</p>
+
+      <button
+        type='button'
+        onClick={S.regenerate}
+      >
+        Regenerate
+      </button>
+    </div>
+  )
+};
+```
+
+## Return Value
+
+```ts
+{
+  salt: string;
+  regenerate: () => void;
+  set: (salt: string) => void;
+  error?: SalterError;
+  resetState: () => void;
+}
+
+export enum SalterError {
+  InvalidHash = 'Invalid salt hash value.',
+}
+```

docs/frontend/react/hooks/contracts/use-tx-events.md

@@ -0,0 +1,25 @@
+---
+title: 'useTxEvents'
+description: 'React hook for collecting and caching events emitted when a transaction is `In Block`'
+---
+
+# useTxEvents
+
+React hook for collecting and caching events emitted when a transaction is `In Block`.
+This differs from [useEvents](/frontend/react/hooks/contracts/use-events). `useEvents`
+will subscribe to any events emitted by a contract. `useTxEvents` accepts a transaction as
+an argument and will collect and cache the events emitted by that single transaction only.
+This is used internally in transaction hooks, which will already provide `events` as state.
+
+## Usage
+
+See [useage inside of the useink library](https://github.com/paritytech/useink/blob/0f44e1b0eee56cb2724a5b39edfc73937b8c4677/packages/useink/src/react/hooks/contracts/useDeployer/useDeployer.ts#L45).
+
+## Return Value
+
+```ts
+{
+  resetState: () => void;
+  events: EventRecord[];
+}
+```

docs/frontend/utils/events/contracts/instantiated.md

@@ -0,0 +1,34 @@
+---
+title: Contracts::Instantiated
+description: Utilties for use with Contracts::Instantiated events
+---
+
+# Contracts::Instantiated
+
+Utilties for use with ContractInstantiated events that are emitted in the `In Block` phase
+of a transaction. This is emitted during the successful deployment of a contract.
+
+## Basic Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```ts
+import { isContractInstantiatedEvent, asContractInstantiatedEvent } from 'useink/utils';
+
+console.log(isContractInstantiatedEvent(eventRecord)) // true or false
+
+const instantiated = asContractInstantiatedEvent(eventRecord);
+console.log(instantiated?.contractAddress) // string | undefined
+console.log(instantiated?.deployer) // string | undefined
+```
+
+## Returns
+
+```ts
+// asContractInstantiatedEvent
+{
+  name: string;
+  deployer: string;
+  contractAddress: string;
+}
+```

docs/frontend/utils/events/format-event-name.md

@@ -0,0 +1,24 @@
+---
+title: formatEventName
+description: A helper function to get a formatted name for an event.
+---
+
+# formatEventName
+
+A helper function to get a formatted name for an event.
+
+## Basic Usage
+
+See [example in the playground dApp](https://github.com/paritytech/useink/blob/main/playground/src/components/pg-deploy/DeployPage.tsx).
+
+```ts
+import { formatEventName } from 'useink/utils';
+
+console.log(formatEventName(eventRecord)) // a string formatted as `${event.section}:${event.method}`
+```
+
+## Returns
+
+```ts
+string
+```