HSG & MHSG Handlers

The following section describes a different way of interacting with HSG and MHSG instances, than documented in the previous sections. In particular, in the previous sections, for each operation on the HSG and MHSG contracts, there's a matching function in the SDK.

In addition to these individual functions, the SDK also includes a single handler for calling the write operations of both HSG and MHSG instances. This enables HSG/MHSG interactions to be optionally handled in a similar way to Hats Modules interactions, by working with the HSG and MHSG metadata objects and the single write functions handler.

Handlers

callInstanceWriteFunction

Call a HSG/MHSG instance's write function.

const res = await hatsSignerGateClient.callInstanceWriteFunction({
    account,
    type,
    instance,
    func,
    args,
});

Arguments:

{
    account: Account | Address;
    type: HsgType;
    instance: Address;
    func: WriteFunction;
    args: unknown[];
}

• account - Viem account (Address for JSON-RPC accounts or Account for other types).

• type - 'HSG' or 'MHSG'.

• instance - The MHSG/HSG instance address.

• func - The write function to call, provided as an object of type WriteFunction.
• args - The arguments with which to call the function, as objects of type WriteFunctionArg.

Response:

{
  status: "success" | "reverted";
  transactionHash: `0x${string}`;
}

• status - "success" if transaction was successful, "reverted" if transaction reverted.

• transactionHash - transaction's hash.

getInstanceParameters

Get a HSG or MHSG instance live parameters:

• Safe address

• Min threshold

• Target threshold

• Max signers

• Owner Hat

const params = await hatsSignerGateClient.getInstanceParameters(instance);

Arguments:

instance: `0x${string}`

instance - Instance's address.

Response:

{
  label: string;
  value: unknown;
  solidityType: string;
  displayType: string;
}[]

An array of objects, each containing a parameter's information:

• label - The parameter's name/description.

• value - The parameter's value, as was returned from the instance contract.

• solidityType - The parameter's Solidity type.

• displayType- The parameter's display type. Its purpose is for UIs to be able to render an appropriate component for the parameter

Metadata

Both the HSG and MHSG metadata objects include their ABIs, all their write functions together with the metadata of each function and the custom roles that are associated with them.

getMetadata

Get the metadata object of HSG or MHSG.

const metadata = await hatsSignerGateClient.getMetadata(type);

Arguments:

HsgType

"HSG" or "MHSG"

Response:

HsgMetadata

An object of type HsgMetadata.

Types

HsgMetadata

Represents a HSG or MHSG metadata object.

{
  customRoles: Role[]; // HSG/MHSG custom roles
  writeFunctions: WriteFunction[]; // HSG/MHSG write functions
  abi: Abi; // HSG/MHSG ABI
}

Role

A custom HSG/MHSG role. Each role is associated with a hat and grants permissions to the hat's wearer(s) to call certain functions on the contract.

There are two special roles with a reserved ID:

1. public role, associated with functions that are permitted to any caller.

2. hatAdmins role, associated with functions that are permitted to the target hat's admins.

{
  id: string; // role's ID
  name: string; // role's name
  criteria: string; // The name of the contract function which can be used to retrieve the role's hat
  hatAdminsFallback?: boolean; // 'true' indicates that the role is granted to the target hat's admin(s) if/when the role's criteria function returns zero.
}

WriteFunction

The HSG/MHSG write functions. Each write function is associated with a role that grants permissions to the role's wearer(s) to call the function on the contract.

{
  roles: string[]; // IDs of the roles that have the authority to call the function
  functionName: string; // the name of the function in the contract
  label: string; // the name to be displayed to end users
  description: string; // a description of the function to be displayed to end users
  primary?: boolean; // 'true' indicates that this function is the primary function of the roles it is associated with. Front ends can use this information to display the function more prominently for each role
  args: WriteFunctionArg[]; // the arguments of the function
}

WriteFunctionArg

HSG/MHSG write function argument.

{
  name: string; // arg's name
  description: string; // arg's description
  type: string; // arg's solidity type, e.g. 'uint256'
  displayType: string; // a free-text field that tells front ends how to generate a proper UI component for the parameter
  optional?: boolean; // setting to 'true' indicates that this input is optional
}