Docs
chromia.com

Use auth descriptors

On this page

The FT4 client library provides flexible tools for creating Single-Signature (SingleSig) and Multi-Signature (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: 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: 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
  2. createMultiSigAuthDescriptorRegistration

Function: 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

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 or 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 for single-key auth or MultiSig for multi-key requirements.