# Use auth descriptors · Chromia Docs (concept)

> The FT4 client library provides flexible tools for creating Single-Signature (SingleSig) and Multi-Signature (MultiSig) auth descriptors, along with optional…

Source: https://docs.chromia.com/build/ft4/client/client-auth-descriptors/

# Use auth descriptors

On this page

* [Auth descriptor structure](#auth-descriptor-structure)
* [Creating auth descriptors](#creating-auth-descriptors)
* [Using rules in auth descriptors](#using-rules-in-auth-descriptors)
* [Examples of creating auth descriptors](#examples-of-creating-auth-descriptors)
* [Instantiation steps](#instantiation-steps)
* [Key points to remember](#key-points-to-remember)

The FT4 client library provides flexible tools for creating **Single-Signature ([`SingleSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.SingleSig/))** and **Multi-Signature
([`MultiSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.MultiSig/))** auth descriptors, along with optional rules to customize the permissions.

This document explains the implementation details and demonstrates how to create and instantiate auth descriptors for
various use cases.

### **Auth descriptor structure**

An auth descriptor is represented by the following TypeScript type:

#### **`AuthDescriptor<T>`**

TypeScript

```
export type AuthDescriptor<T extends SingleSig | MultiSig> = {
  id: Buffer; // Unique identifier
  accountId: Buffer; // Account to which this auth descriptor belongs
  authType: AuthType; // "S" for SingleSig, "M" for MultiSig
  rules: AuthDescriptorRules | null; // Optional rules for descriptor
  created: Date; // Creation timestamp
  args: T; // Signature details (SingleSig or MultiSig)
};
```

#### **Types of signatures**

* **[`SingleSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.SingleSig/):** Used for single-key authentication.

  TypeScript

  ```
  export type SingleSig = {
    flags: string[]; // Permissions (e.g., "A", "T")
    signer: Buffer; // Public key for the single signer
  };
  ```
* **[`MultiSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.MultiSig/):** Used for multi-key authentication.

  TypeScript

  ```
  export type MultiSig = {
    flags: string[]; // Permissions
    signaturesRequired: number; // Number of signatures required for operation
    signers: Buffer[]; // List of public keys
  };
  ```

### **Creating auth descriptors**

The FT4 library provides two primary functions for creating auth descriptors:

1. **[`createSingleSigAuthDescriptorRegistration`](https://docs.chromia.com/pages/ft4-ts-client/functions/accounts.createSingleSigAuthDescriptorRegistration/)**
2. **[`createMultiSigAuthDescriptorRegistration`](https://docs.chromia.com/pages/ft4-ts-client/functions/accounts.createMultiSigAuthDescriptorRegistration/)**

#### **Function: [`createSingleSigAuthDescriptorRegistration`](https://docs.chromia.com/pages/ft4-ts-client/functions/accounts.createSingleSigAuthDescriptorRegistration/)**

Creates a SingleSig auth descriptor with the specified permissions, public key, and optional rules.

* **Parameters:**

  + `flags: string[]` - List of permissions (e.g., `["A"]` for account edits, `["T"]` for transfers).
  + `pubKey: Buffer` - Public key of the signer.
  + `rules?: AuthDescriptorRules` - Optional rules for the descriptor.
* **Example:**

  TypeScript

  ```
  const authDesc = createSingleSigAuthDescriptorRegistration(["A", "T"], pubKey);
  ```

#### **Function: [`createMultiSigAuthDescriptorRegistration`](https://docs.chromia.com/pages/ft4-ts-client/functions/accounts.createMultiSigAuthDescriptorRegistration/)**

Creates a MultiSig auth descriptor with the specified permissions, multiple public keys, the number of required
signatures, and optional rules.

* **Parameters:**

  + `flags: string[]` - List of permissions.
  + `pubKeys: Buffer[]` - List of public keys.
  + `signaturesRequired: number` - Number of required signatures.
  + `rules?: AuthDescriptorRules` - Optional rules for the descriptor.
* **Example:**

  TypeScript

  ```
  const authDesc = createMultiSigAuthDescriptorRegistration(["T"], [pubKey1, pubKey2], 2);
  ```

### **Using rules in auth descriptors**

Rules further refine the conditions under which auth descriptors can be used. These can be **simple** or **complex**.

#### **Simple rule**

A simple rule specifies a condition for a single variable.

* **Structure:**

  TypeScript

  ```
  export type SimpleRule<T extends string> = {
    variable: T; // Variable being constrained (e.g., opCount)
    operator: RuleOperator; // Comparison operator (e.g., lessThan)
    value: number; // Value to compare against
  };
  ```
* **Example:** "Expire after 2 uses"

  TypeScript

  ```
  const rule = { variable: "opCount", operator: "lessThan", value: 2 };
  ```

#### **Complex rule**

A complex rule combines multiple simple rules using logical operators (e.g., "and").

* **Structure:**

  TypeScript

  ```
  export type ComplexRule<T extends string> = {
    operator: "and";
    rules: SimpleRule<T>[];
  };
  ```
* **Example:** "Expire after 2 uses and only allow transfers"

  TypeScript

  ```
  const complexRule = {
    operator: "and",
    rules: [
      { variable: "opCount", operator: "lessThan", value: 2 },
      { variable: "permissions", operator: "equals", value: "T" },
    ],
  };
  ```

### **Examples of creating auth descriptors**

#### **Single-sig example**

"Whenever the public key signs, they can edit the account or transfer funds."

TypeScript

```
const authDesc = createSingleSigAuthDescriptorRegistration(["A", "T"], pubKey);
```

#### **Multi-sig example 1**

"Whenever both pubKey1 and pubKey2 sign, they can transfer funds."

TypeScript

```
const authDesc = createMultiSigAuthDescriptorRegistration(["T"], [pubKey1, pubKey2], 2);
```

#### **Multi-sig example 2**

"The first time 3 out of 5 keys sign, they can edit the account."

TypeScript

```
const authDesc = createMultiSigAuthDescriptorRegistration(["A"], [pubKey1, pubKey2, pubKey3, pubKey4, pubKey5], 3, {
  variable: "opCount",
  operator: "lessThan",
  value: 2,
});
```

#### **Instantiate rules**

Here's a few example of possible rules which can be created:

TypeScript

```
// Example rules
const lessThanThreeTimes = lessThan(opCount(3));
const untilBlock100 = lessOrEqual(blockHeight(100));
const during2024 = and(
  greaterOrEqual(blockTime(1704067200000)), /Jan 1st, 2024 (millisecond timestamp)
  lessThan(blockTime(1735689600000)) /Jan 1st, 2025
);
const onceDuring2024 = and(
  greaterOrEqual(blockTime(1704067200000)), /Jan 1st, 2024
  lessThan(blockTime(1735689600000)), /Jan 1st, 2025
  lessThan(opCount(2))
);
```

### **Instantiation steps**

1. **Generate key pairs** Create or load the public/private key pairs:

   TypeScript

   ```
   const pubKey1 = Buffer.from("public_key_1_hex", "hex");
   const pubKey2 = Buffer.from("public_key_2_hex", "hex");
   ```
2. **Define permissions** Use flags like `["A"]` for account editing or `["T"]` for transfers.
3. **Add rules (optional)** Specify simple or complex rules for additional constraints.
4. **Create the auth descriptor** Use the appropriate function for [`SingleSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.SingleSig/) or [`MultiSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.MultiSig/) auth descriptors.

---

### **Key points to remember**

* **Flags:** Control what the auth descriptor allows (e.g., "A" for account editing, "T" for transfers).
* **Rules:** Add constraints like expiration or operational limits.
* **Signature type:** Choose [`SingleSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.SingleSig/) for single-key auth or [`MultiSig`](https://docs.chromia.com/pages/ft4-ts-client/types/accounts.MultiSig/) for multi-key requirements.

[View this page on docs.chromia.com](https://docs.chromia.com/build/ft4/client/client-auth-descriptors/)Content mirrored from the live docs
