From 84eb65256a9a84b4ad70ecf21aaec6bdab48f312 Mon Sep 17 00:00:00 2001 From: ponderingdemocritus Date: Thu, 21 Dec 2023 17:40:46 +1100 Subject: [PATCH] burner docs first pass --- .../create-burner/src/connectors/burner.ts | 16 ++++--- packages/create-burner/src/constants/index.ts | 22 ++++++++++ .../src/context/burnerProvider.tsx | 26 +++++++++++ packages/create-burner/src/hooks/useBurner.ts | 29 ++++++++++--- .../src/hooks/useBurnerManager.ts | 12 +++--- .../src/manager/burnerManager.ts | 43 +++++++++++++++++++ 6 files changed, 130 insertions(+), 18 deletions(-) diff --git a/packages/create-burner/src/connectors/burner.ts b/packages/create-burner/src/connectors/burner.ts index 3b210b6f..9bca308e 100644 --- a/packages/create-burner/src/connectors/burner.ts +++ b/packages/create-burner/src/connectors/burner.ts @@ -1,27 +1,29 @@ import { AccountInterface, Account } from "starknet"; import { Connector } from "@starknet-react/core"; -/* - This is a custom connector to use within Starknet React. -*/ - +/** + * + * @class BurnerConnector + * + * @description Extends the Connector class and implements the AccountInterface. + * This class is used to connect to the Burner Wallet. + * + * + */ export class BurnerConnector extends Connector { private _account: AccountInterface | Account | null; public _name: string = "Burner Connector"; - // Use the "options" type as per your need. Here, I am assuming it to be an object. constructor(options: object, account: AccountInterface | Account | null) { super({ options }); this._account = account; } available(): boolean { - // Implement your logic here. return true; } async ready(): Promise { - // Implement your logic here. return true; } diff --git a/packages/create-burner/src/constants/index.ts b/packages/create-burner/src/constants/index.ts index 4b0b82ed..e2415f34 100644 --- a/packages/create-burner/src/constants/index.ts +++ b/packages/create-burner/src/constants/index.ts @@ -1,7 +1,29 @@ +/** + * @ignore + * + * `@hidden` and `@ignore` keep the subsequent code from being documented. + */ export const OPENZEPPELIN_ACCOUNT_GOERLI = "0x2f318C334780961FB129D2a6c30D0763d9a5C970"; +/** + * @ignore + * + * `@hidden` and `@ignore` keep the subsequent code from being documented. + */ export const PREFUND_AMOUNT = "0x2386f26fc10000"; // 0.001ETH + +/** + * @ignore + * + * `@hidden` and `@ignore` keep the subsequent code from being documented. + */ export const KATANA_ETH_CONTRACT_ADDRESS = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"; + +/** + * @ignore + * + * `@hidden` and `@ignore` keep the subsequent code from being documented. + */ export const KATANA_ACCOUNT_CLASS_HASH = "0x04d07e40e93398ed3c76981e72dd1fd22557a78ce36c0515f679e27f0bb5bc5f"; diff --git a/packages/create-burner/src/context/burnerProvider.tsx b/packages/create-burner/src/context/burnerProvider.tsx index 6b63b775..77740a80 100644 --- a/packages/create-burner/src/context/burnerProvider.tsx +++ b/packages/create-burner/src/context/burnerProvider.tsx @@ -3,11 +3,37 @@ import { BurnerManagerOptions } from "../types"; export const BurnerContext = createContext(null); +/** + * Props for the BurnerProvider component {@link BurnerProvider} + */ interface BurnerProviderProps { children: ReactNode; initOptions: BurnerManagerOptions; } +/** + * BurnerProvider + * + * @description This wraps the entire application in a context provider to allow for access to keep + * the burner manager options available to all components. Takes {@link BurnerProviderProps}. + * + * ```tsx + * import { BurnerProvider } from '@dojoengine/create-burner'; + * + * const initOptions = { ... }; + * + * const App = () => { + * return ( + * + * + * + * )}; + * ``` + * + * @param children + * @param initOptions + */ + export const BurnerProvider = ({ children, initOptions, diff --git a/packages/create-burner/src/hooks/useBurner.ts b/packages/create-burner/src/hooks/useBurner.ts index 4ad2f485..77f5f1dc 100644 --- a/packages/create-burner/src/hooks/useBurner.ts +++ b/packages/create-burner/src/hooks/useBurner.ts @@ -7,7 +7,29 @@ import { Burner } from "../types"; /** * A React hook to manage Burner accounts. - * Provides utility methods like get, list, select, and create. + * This hook exposes methods and properties to manage Burner accounts. + * You need to use this within a {@link BurnerProvider} context. + * + * @example + * ```tsx + * import { useBurner } from "@dojoengine/create-burner"; + * + * const MyComponent = () => { + * const { list, select, create } = useBurner(); + * const burners = list(); + * + * return ( + *
+ * + * {burners.map((burner) => ( + * + * ))} + *
+ * ); + * }; + * ``` * * @returns An object with utility methods and properties. */ @@ -18,17 +40,14 @@ export const useBurner = () => { throw new Error("useBurner must be used within a BurnerProvider"); } - // Initialize the BurnerManager with the provided options. + /** Initialize the BurnerManager with the provided options. */ const burnerManager = useMemo( () => new BurnerManager(initParams), [initParams] ); - // State to manage the current active account. const [account, setAccount] = useState(null); - const [burnerUpdate, setBurnerUpdate] = useState(0); - const [isDeploying, setIsDeploying] = useState(false); // On mount, initialize the burner manager and set the active account. diff --git a/packages/create-burner/src/hooks/useBurnerManager.ts b/packages/create-burner/src/hooks/useBurnerManager.ts index f34475f0..865cbcdc 100644 --- a/packages/create-burner/src/hooks/useBurnerManager.ts +++ b/packages/create-burner/src/hooks/useBurnerManager.ts @@ -13,7 +13,7 @@ import { Burner } from "../types"; export const useBurnerManager = ({ burnerManager, }: { - burnerManager: BurnerManager; // Accepts the BurnerManager class as an optional parameter + burnerManager: BurnerManager; // Accepts the BurnerManager class as an parameter }) => { if (!burnerManager.masterAccount) { throw new Error("BurnerManagerClass must be provided"); @@ -21,9 +21,7 @@ export const useBurnerManager = ({ // State to manage the current active account. const [account, setAccount] = useState(null); - const [burnerUpdate, setBurnerUpdate] = useState(0); - const [isDeploying, setIsDeploying] = useState(false); // On mount, initialize the burner manager and set the active account. @@ -124,11 +122,13 @@ export const useBurnerManager = ({ */ const applyFromClipboard = useCallback(async () => { await burnerManager.setBurnersFromClipboard(); - setAccount(burnerManager.getActiveAccount()); // set the active account - setBurnerUpdate((prev) => prev + 1); // re-fetch of the list + + // Update the burnerUpdate state to trigger a re-render. + setAccount(burnerManager.getActiveAccount()); + + setBurnerUpdate((prev) => prev + 1); }, [burnerManager]); - // Expose methods and properties for the consumers of this hook. return { get, list, diff --git a/packages/create-burner/src/manager/burnerManager.ts b/packages/create-burner/src/manager/burnerManager.ts index 9be8ed2b..4a0e9e09 100644 --- a/packages/create-burner/src/manager/burnerManager.ts +++ b/packages/create-burner/src/manager/burnerManager.ts @@ -3,6 +3,49 @@ import { Burner, BurnerManagerOptions, BurnerStorage } from "../types"; import Storage from "../utils/storage"; import { prefundAccount } from "./prefundAccount"; +/** + * A class to manage Burner accounts. + * This class exposes methods and properties to manage Burner accounts. + * This class uses LocalStorage to store the Burner accounts. + * You can use this class to build your own Burner Wallet in any js framework. + * + * @example + * + * ```ts + * export const createBurner = async () => { + * const rpcProvider = new RpcProvider({ + * nodeUrl: import.meta.env.VITE_PUBLIC_NODE_URL!, + * }); + * + * const masterAccount = new Account( + * rpcProvider, + * import.meta.env.VITE_PUBLIC_MASTER_ADDRESS!, + * import.meta.env.VITE_PUBLIC_MASTER_PRIVATE_KEY! + * ); + * + * const burnerManager = new BurnerManager({ + * masterAccount, + * accountClassHash: import.meta.env.VITE_PUBLIC_ACCOUNT_CLASS_HASH!, + * rpcProvider, + * }); + * + * try { + * await burnerManager.create(); + * } catch (e) { + * console.log(e); + * } + * + * burnerManager.init(); + * + * return { + * account: burnerManager.account as Account, + * burnerManager, + * }; + * }; + * + * + */ + export class BurnerManager { public masterAccount: Account; public accountClassHash: string;