feat(docs): updated custom instruction typescript guide

Author: nikerzetic-aflabs

docs/smart-accounts/guides/typescript-viem/03-custom-instruction.mdx

@@ -164,6 +164,16 @@ As described in the general [Custom Instruction guide](/smart-accounts/custom-in
 Behind the scenes, each custom instruction call translates to sending a payment transaction to the `targetContract` address of `value` FLR with attached `data`.
 :::
 
+We define the `CustomInstruction` type:
+
+```typescript
+export type CustomInstruction = {
+  targetContract: Address;
+  value: bigint;
+  data: `0x${string}`;
+};
+```
+
 The `targetContract` and `value` do not need additional processing, but how can we generate the calldata?
 For that, we will use the `encodeFunctionData` function from the Viem library.
 It calculates the encoding for a function from its contract's ABI, the function name, and the arguments used.
@@ -236,7 +246,6 @@ Then we call the `writeContract` Viem function, and actually register the instru
 
 If the instruction has already been registered, a `CustomInstructionAlreadyRegistered` event is emitted.
 Otherwise, the instruction is registered, and a `CustomInstructionRegistered` event is emitted instead.
-In either case, the 32-byte encoding of the custom instruction, called the `callHash`, is returned.
 
 ```typescript
 export async function registerCustomInstruction(
@@ -251,35 +260,43 @@ export async function registerCustomInstruction(
   });
   console.log("request:", request, "\n");
 
-  const registerCustomInstructionResult =
+  const registerCustomInstructionTransaction =
     await walletClient.writeContract(request);
   console.log(
-    "registerCustomInstructionResult:",
-    registerCustomInstructionResult,
+    "Register custom instruction transaction:",
+    registerCustomInstructionTransaction,
     "\n",
   );
 
-  return registerCustomInstructionResult;
+  return registerCustomInstructionTransaction;
 }
 ```
 
 ## Encoding an instruction
 
 Before the custom instruction can be sent on the XRPL, it must be properly encoded.
-The 32-byte `callHash` that the `registerCustomInstruction` function returns is not yet a proper instruction encoding.
+We call the `encodeCustomInstruction` read function of the `MasterAccountController` contract with the instruction as parameter.
+It returns a 32-byte `callHash`, which is not yet a proper instruction encoding.
 We need to replace the first two bytes with the following values:
 
 - 1st byte: custom instruction command ID `0xff`
 - 2nd byte: wallet identifier `walletId` described above
 
 ```typescript
-export function encodeCustomInstruction(
-  instructionHash: `0x${string}`,
+async function encodeCustomInstruction(
+  instructions: CustomInstruction[],
   walletId: number,
 ) {
+  const encodedInstruction = (await publicClient.readContract({
+    address: MASTER_ACCOUNT_CONTROLLER_ADDRESS,
+    abi: abi,
+    functionName: "encodeCustomInstruction",
+    args: [instructions],
+  })) as `0x${string}`;
+  // NOTE:(Nik) We cut off the `0x` prefix and the first 2 bytes to get the length down to 30 bytes
   return ("0xff" +
     toHex(walletId, { size: 1 }).slice(2) +
-    instructionHash.slice(6)) as `0x${string}`;
+    encodedInstruction.slice(6)) as `0x${string}`;
 }
 ```
 
@@ -411,7 +428,7 @@ async function waitForCustomInstructionExecutedEvent({
 }
 ```
 
-    The vehicle for bridging the instruction is FDC, which puts a maximum cap of 180 seconds on the process duration.
+The vehicle for bridging the instruction is FDC, which puts a maximum cap of 180 seconds on the process duration.
 
 ## Full script
 
@@ -420,3 +437,91 @@ The repository with the above example is available on [GitHub](https://github.co
 <CodeBlock language="typescript" title="src/custom-instructions.ts">
   {CustomInstructionsScript}
 </CodeBlock>
+
+## Expected output
+
+```bash
+Custom instructions: [
+  {
+    targetContract: '0xEE6D54382aA623f4D16e856193f5f8384E487002',
+    value: 0n,
+    data: '0x80abd133'
+  },
+  {
+    targetContract: '0x42Ccd4F0aB1C6Fa36BfA37C9e30c4DC4DD94dE42',
+    value: 1000000000000000000n,
+    data: '0xd0e30db0'
+  },
+  {
+    targetContract: '0x59D57652BF4F6d97a6e555800b3920Bd775661Dc',
+    value: 1000000000000000000n,
+    data: '0x28d106b20000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000c48656c6c6f20576f726c64210000000000000000000000000000000000000000'
+  }
+]
+
+Personal account address: 0xFd2f0eb6b9fA4FE5bb1F7B26fEE3c647ed103d9F
+
+request: {
+  abi: [
+    {
+      inputs: [Array],
+      name: 'registerCustomInstruction',
+      outputs: [Array],
+      stateMutability: 'nonpayable',
+      type: 'function'
+    }
+  ],
+  address: '0x434936d47503353f06750Db1A444DBDC5F0AD37c',
+  args: [ [ [Object], [Object], [Object] ] ],
+  dataSuffix: undefined,
+  functionName: 'registerCustomInstruction',
+  account: {
+    address: '0xF5488132432118596fa13800B68df4C0fF25131d',
+    nonceManager: undefined,
+    sign: [AsyncFunction: sign],
+    signAuthorization: [AsyncFunction: signAuthorization],
+    signMessage: [AsyncFunction: signMessage],
+    signTransaction: [AsyncFunction: signTransaction],
+    signTypedData: [AsyncFunction: signTypedData],
+    source: 'privateKey',
+    type: 'local',
+    publicKey: '0x04cd84974fb965b048aa4230fdf0a2735c951f28b076727e1067bf56577a59b1cbc41e8d03b33acc9105828f048c0cf940c78bba518b0da2765078ca2a42e056c3'
+  }
+}
+
+Register custom instruction transaction: 0x2f6500791d89ea7f8ff5f3ce8983d92d7aaf62e04207513e8e0b2a2bfdf09a1e
+
+Custom instruction call hash: 0x2f6500791d89ea7f8ff5f3ce8983d92d7aaf62e04207513e8e0b2a2bfdf09a1e
+
+Encoded instructions: 0xff00e54bf1b4e93c5306e08d919864ec111211c4fb36960261e8018da9959791
+
+instructionIdDecimal: 255n
+
+Instruction fee: 0.001
+
+Custom instruction transaction hash: 03165B82E4B7BB168AF7B217C9EC833896E968C796CA8BF8D2E66879ED311909
+
+Waiting for CustomInstructionExecuted event...
+CustomInstructionExecuted event: {
+  eventName: 'CustomInstructionExecuted',
+  args: {
+    personalAccount: '0xFd2f0eb6b9fA4FE5bb1F7B26fEE3c647ed103d9F',
+    callHash: '0x0000e54bf1b4e93c5306e08d919864ec111211c4fb36960261e8018da9959791',
+    customInstruction: [ [Object], [Object], [Object] ]
+  },
+  address: '0x434936d47503353f06750db1a444dbdc5f0ad37c',
+  topics: [
+    '0x1c09418c54894f576841186935c5f666b3bedd66c29f3a03bcab4051fe2509f3',
+    '0x000000000000000000000000fd2f0eb6b9fa4fe5bb1f7b26fee3c647ed103d9f',
+    '0x0000e54bf1b4e93c5306e08d919864ec111211c4fb36960261e8018da9959791'
+  ],
+  data: '0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001a0000000000000000000000000ee6d54382aa623f4d16e856193f5f8384e48700200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000480abd1330000000000000000000000000000000000000000000000000000000000000000000000000000000042ccd4f0ab1c6fa36bfa37c9e30c4dc4dd94de420000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000004d0e30db00000000000000000000000000000000000000000000000000000000000000000000000000000000059d57652bf4f6d97a6e555800b3920bd775661dc0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000006428d106b20000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000c48656c6c6f20576f726c6421000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+  blockNumber: 26663892n,
+  transactionHash: '0xe3ba1751d63a9b11ff3b3185254c28c447f1db6ff101708f6968ff935c28e3f3',
+  transactionIndex: 2,
+  blockHash: '0x69a3b948a56a5195fbe0ced46b157ca33390226a4503f59a3d8e59fe07538d23',
+  logIndex: 7,
+  removed: false,
+  blockTimestamp: undefined
+}
+```

examples/developer-hub-javascript/smart-accounts/custom-instructions.ts

@@ -15,15 +15,22 @@ import { publicClient } from "./utils/client";
 import { sendXrplPayment } from "./utils/xrpl";
 import { Client, Wallet } from "xrpl";
 import type { CustomInstructionExecutedEventType } from "./utils/event-types";
+import { abi } from "./abis/CustomInstructionsFacet";
 
-export function encodeCustomInstruction(
-  instructionHash: `0x${string}`,
+async function encodeCustomInstruction(
+  instructions: CustomInstruction[],
   walletId: number,
 ) {
+  const encodedInstruction = (await publicClient.readContract({
+    address: MASTER_ACCOUNT_CONTROLLER_ADDRESS,
+    abi: abi,
+    functionName: "encodeCustomInstruction",
+    args: [instructions],
+  })) as `0x${string}`;
   // NOTE:(Nik) We cut off the `0x` prefix and the first 2 bytes to get the length down to 30 bytes
   return ("0xff" +
     toHex(walletId, { size: 1 }).slice(2) +
-    instructionHash.slice(6)) as `0x${string}`;
+    encodedInstruction.slice(6)) as `0x${string}`;
 }
 
 async function sendCustomInstruction({
@@ -145,10 +152,11 @@ async function main() {
   );
   console.log("Personal account address:", personalAccountAddress, "\n");
 
-  const customInstructionHash =
+  const customInstructionCallHash =
     await registerCustomInstruction(customInstructions);
-  const encodedInstruction = encodeCustomInstruction(
-    customInstructionHash,
+  console.log("Custom instruction call hash:", customInstructionCallHash, "\n");
+  const encodedInstruction = await encodeCustomInstruction(
+    customInstructions,
     walletId,
   );
   console.log("Encoded instructions:", encodedInstruction, "\n");