write docs

ensdomains · Jun 29, 2023 · 316c090 · 316c090
1 parent 9488f29
commit 316c090
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 14 deletions.
diff --git a/packages/ensjs/src/functions/write/unwrapName.ts b/packages/ensjs/src/functions/write/unwrapName.ts
@@ -24,8 +24,11 @@ import { getNameType } from '../../utils/getNameType'
 import { makeLabelNodeAndParent } from '../../utils/makeLabelNodeAndParent'
 
 type BaseUnwrapNameDataParameters<TName extends string> = {
+  /** The name to unwrap */
   name: TName
+  /** The recipient of the unwrapped name */
   newOwnerAddress: Address
+  /** The registrant of the unwrapped name (eth-2ld only) */
   newRegistrantAddress?: Address
 }
 
@@ -112,6 +115,33 @@ export const makeFunctionData = <
   }
 }
 
+/**
+ * Unwraps a name.
+ * @param wallet - {@link WalletWithEns}
+ * @param parameters - {@link UnwrapNameParameters}
+ * @returns Transaction hash. {@link UnwrapNameReturnType}
+ *
+ * @example
+ * import { createPublicClient, createWalletClient, http, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addContracts, unwrapName } from '@ensdomains/ensjs'
+ *
+ * const [mainnetWithEns] = addContracts([mainnet])
+ * const client = createPublicClient({
+ *   chain: mainnetWithEns,
+ *   transport: http(),
+ * })
+ * const wallet = createWalletClient({
+ *   chain: mainnetWithEns,
+ *   transport: custom(window.ethereum),
+ * })
+ * const hash = await unwrapName(wallet, {
+ *   name: 'example.eth',
+ *   newOwnerAddress: '0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7',
+ *   newRegistrantAddress: '0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7',
+ * })
+ * // 0x...
+ */
 async function unwrapName<
   TName extends string,
   TChain extends ChainWithEns,

diff --git a/packages/ensjs/src/functions/write/wrapName.test.ts b/packages/ensjs/src/functions/write/wrapName.test.ts
@@ -50,7 +50,7 @@ describe('eth 2ld', () => {
   it('should return a wrap name transaction and succeed', async () => {
     const tx = await wrapName(walletClient, {
       name: 'test123.eth',
-      wrappedOwner: accounts[2],
+      newOwnerAddress: accounts[2],
       account: accounts[1],
     })
     expect(tx).toBeTruthy()
@@ -66,7 +66,7 @@ describe('eth 2ld', () => {
   it('should allow initial fuses', async () => {
     const tx = await wrapName(walletClient, {
       name: 'test123.eth',
-      wrappedOwner: accounts[2],
+      newOwnerAddress: accounts[2],
       fuses: {
         named: ['CANNOT_UNWRAP', 'CANNOT_SET_TTL'],
       },
@@ -84,7 +84,7 @@ describe('eth 2ld', () => {
   it('should allow a non-default resolver address', async () => {
     const tx = await wrapName(walletClient, {
       name: 'test123.eth',
-      wrappedOwner: accounts[2],
+      newOwnerAddress: accounts[2],
       resolverAddress: '0x42D63ae25990889E35F215bC95884039Ba354115',
       account: accounts[1],
     })
@@ -102,7 +102,7 @@ describe('eth 2ld', () => {
     await expect(
       wrapName(walletClient, {
         name: `${label}.eth`,
-        wrappedOwner: accounts[2],
+        newOwnerAddress: accounts[2],
         account: accounts[1],
       }),
     ).rejects.toThrowErrorMatchingInlineSnapshot(`
@@ -124,7 +124,7 @@ describe('other', () => {
   it('should return a wrap name transaction and succeed', async () => {
     const tx = await wrapName(walletClient, {
       name: 'test.with-subnames.eth',
-      wrappedOwner: accounts[2],
+      newOwnerAddress: accounts[2],
       account: accounts[2],
     })
     expect(tx).toBeTruthy()
@@ -140,7 +140,7 @@ describe('other', () => {
   it('should allow a non-default resolver address', async () => {
     const tx = await wrapName(walletClient, {
       name: 'test.with-subnames.eth',
-      wrappedOwner: accounts[2],
+      newOwnerAddress: accounts[2],
       resolverAddress: '0x42D63ae25990889E35F215bC95884039Ba354115',
       account: accounts[2],
     })
@@ -157,7 +157,7 @@ describe('other', () => {
     await expect(
       wrapName(walletClient, {
         name: 'test.with-subnames.eth',
-        wrappedOwner: accounts[2],
+        newOwnerAddress: accounts[2],
         fuses: {
           named: ['CANNOT_UNWRAP', 'CANNOT_SET_TTL'],
         } as any,
@@ -178,7 +178,7 @@ describe('other', () => {
     await expect(
       wrapName(walletClient, {
         name: `${label}.with-subnames.eth`,
-        wrappedOwner: accounts[2],
+        newOwnerAddress: accounts[2],
         account: accounts[2],
       }),
     ).rejects.toThrowErrorMatchingInlineSnapshot(`

diff --git a/packages/ensjs/src/functions/write/wrapName.ts b/packages/ensjs/src/functions/write/wrapName.ts
@@ -31,11 +31,15 @@ export type WrapNameDataParameters<
   TName extends string,
   TNameOption extends GetNameType<TName> = GetNameType<TName>,
 > = {
+  /** The name to wrap */
   name: TName
-  wrappedOwner: Address
+  /** The recipient of the wrapped name */
+  newOwnerAddress: Address
+  /** Fuses to set on wrap (eth-2ld only) */
   fuses?: TNameOption extends Eth2ldNameSpecifier
     ? CombinedFuseInput['child']
     : never
+  /** The resolver address to set on wrap */
   resolverAddress?: Address
 }
 
@@ -61,7 +65,7 @@ export const makeFunctionData = <
   wallet: WalletWithEns<Transport, TChain, TAccount>,
   {
     name,
-    wrappedOwner,
+    newOwnerAddress,
     fuses,
     resolverAddress = getChainContractAddress({
       client: wallet,
@@ -89,7 +93,7 @@ export const makeFunctionData = <
         { name: 'ownerControlledFuses', type: 'uint16' },
         { name: 'resolverAddress', type: 'address' },
       ],
-      [labels[0], wrappedOwner, encodedFuses, resolverAddress],
+      [labels[0], newOwnerAddress, encodedFuses, resolverAddress],
     )
 
     return {
@@ -118,11 +122,37 @@ export const makeFunctionData = <
     data: encodeFunctionData({
       abi: wrapSnippet,
       functionName: 'wrap',
-      args: [toHex(packetToBytes(name)), wrappedOwner, resolverAddress],
+      args: [toHex(packetToBytes(name)), newOwnerAddress, resolverAddress],
     }),
   }
 }
 
+/**
+ * Wraps a name.
+ * @param wallet - {@link WalletWithEns}
+ * @param parameters - {@link WrapNameParameters}
+ * @returns Transaction hash. {@link WrapNameReturnType}
+ *
+ * @example
+ * import { createPublicClient, createWalletClient, http, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addContracts, wrapName } from '@ensdomains/ensjs'
+ *
+ * const [mainnetWithEns] = addContracts([mainnet])
+ * const client = createPublicClient({
+ *   chain: mainnetWithEns,
+ *   transport: http(),
+ * })
+ * const wallet = createWalletClient({
+ *   chain: mainnetWithEns,
+ *   transport: custom(window.ethereum),
+ * })
+ * const hash = await wrapName(wallet, {
+ *   name: 'ens.eth',
+ *   newOwnerAddress: '0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7',
+ * })
+ * // 0x...
+ */
 async function wrapName<
   TName extends string,
   TChain extends ChainWithEns,
@@ -132,7 +162,7 @@ async function wrapName<
   wallet: WalletWithEns<Transport, TChain, TAccount>,
   {
     name,
-    wrappedOwner,
+    newOwnerAddress,
     fuses,
     resolverAddress,
     ...txArgs
@@ -143,7 +173,7 @@ async function wrapName<
       ...wallet,
       account: parseAccount((txArgs.account || wallet.account)!),
     } as WalletWithEns<Transport, TChain, Account>,
-    { name, wrappedOwner, fuses, resolverAddress },
+    { name, newOwnerAddress, fuses, resolverAddress },
   )
   const writeArgs = {
     ...data,