Class RoflClient

Client for interacting with the ROFL application daemon REST API.

Provides methods for key generation, metadata management, and authenticated transaction submission to ROFL applications running in trusted execution environments.

Example

// Connect via Unix Domain Socket (default)
const client = new RoflClient();

// Connect via HTTP
const httpClient = new RoflClient({ url: 'http://localhost:8080' });

// Custom socket path with timeout
const customClient = new RoflClient({
  url: '/custom/rofl.sock',
  timeoutMs: 30000
});

Constructors

constructor

Methods

generateKey getAppId getMetadata query setMetadata signAndSubmit

Constructors

constructor

Methods

generateKey

  • generateKey(keyId, kind?): Promise<string>

  • Generate or fetch a cryptographic key from ROFL's decentralized key management system.

    All generated keys are deterministic and tied to the app's identity. They can only be generated inside properly attested app instances and will remain consistent across deployments or state resets.

    Parameters

    • keyId: string

      Domain separator for different keys within the application (e.g., 'signing-key', 'encryption-key')

    • kind: KeyKind = KeyKind.SECP256K1

      Type of key to generate (default: SECP256K1). See KeyKind for available options

    Returns Promise<string>

    Hex-encoded key material without 0x prefix. For cryptographic keys (ED25519, SECP256K1), returns the private key. For entropy types (RAW_256, RAW_384), returns raw random bytes

    Throws

    If key generation fails or response is invalid

    Example

    // Generate a default SECP256K1 key
    const key = await client.generateKey('my-signing-key');

    // Generate an Ed25519 key for a specific purpose
    const ed25519Key = await client.generateKey('my-ed25519-key', KeyKind.ED25519);

    // Generate raw entropy for custom use
    const entropy = await client.generateKey('my-entropy', KeyKind.RAW_256);

getAppId

  • getAppId(): Promise<string>

  • Retrieve the ROFL app identifier in bech32 format.

    The app ID uniquely identifies this ROFL application on-chain and is used for authentication and authorization. This is a convenience method that wraps the /rofl/v1/app/id endpoint.

    Returns Promise<string>

    Bech32-encoded app ID (e.g., 'rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf')

    Throws

    If app ID retrieval fails or response is invalid

    Example

    const appId = await client.getAppId();
    console.log(`My ROFL app ID: ${appId}`);
    // Output: "My ROFL app ID: rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf"

getMetadata

  • getMetadata(): Promise<Record<string, string>>

  • Retrieve all user-set metadata key-value pairs for this ROFL app instance.

    Metadata is automatically namespaced with 'net.oasis.app.' when published in the on-chain ROFL replica registration, but this method returns the raw keys without the namespace prefix.

    Returns Promise<Record<string, string>>

    Dictionary of metadata key-value pairs

    Throws

    If metadata retrieval fails or response is invalid

    Example

    const metadata = await client.getMetadata();
    console.log(metadata);
    // Output: { "version": "1.0.0", "key_fingerprint": "abc123..." }

query

  • query<TArgs, TResult>(method, ...argsTuple): Promise<TResult>

  • Execute a read-only runtime query via ROFL.

    Query arguments and results follow the CBOR schema published by the Oasis runtime. When using the Oasis TypeScript runtime SDK (@oasisprotocol/client-rt), pass the generated types.* definitions as generics to get end-to-end typing:

    Type Parameters

    • TArgs = void
    • TResult = unknown

    Parameters

    • method: string

      Fully-qualified runtime method name (e.g., 'rofl.App')

    • Rest...argsTuple: QueryArgsTuple<TArgs>

    Returns Promise<TResult>

    Decoded query response body

    Example

    import {rofl, types} from '@oasisprotocol/client-rt';

    const config = await client.query<types.RoflAppQuery, types.RoflAppConfig>(
      rofl.METHOD_APP,
      {id: myAppId},
    );

setMetadata

  • setMetadata(metadata): Promise<void>

  • Set metadata key-value pairs for this ROFL app instance.

    This replaces all existing app-provided metadata. If the metadata has changed, it will trigger an automatic on-chain registration refresh. Keys are automatically namespaced with 'net.oasis.app.' when published on-chain.

    Metadata is validated against runtime-configured limits (typically max 64 pairs, max key size 1024 bytes, max value size 16KB).

    Parameters

    • metadata: Record<string, string>

      Dictionary of metadata key-value pairs to set

    Returns Promise<void>

    Promise that resolves when metadata is successfully updated

    Throws

    If metadata validation fails or update is rejected

    Example

    // Publish app version and key fingerprint
    await client.setMetadata({
      version: '1.0.0',
      key_fingerprint: 'abc123...'
    });

    // Clear all metadata by setting empty object
    await client.setMetadata({});

signAndSubmit

  • signAndSubmit(tx, opts?): Promise<Uint8Array>

  • Sign and submit an authenticated transaction via ROFL.

    Parameters

    • tx: StdTx | EthTx

      A StdTx or EthTx. Hex fields may include a 0x prefix; it will be stripped.

    • Optionalopts: {
          encrypt?: boolean;
      }
      • Optionalencrypt?: boolean

        Whether to encrypt calldata. Defaults to true (server default).

    Returns Promise<Uint8Array>

    Raw CBOR-encoded CallResult bytes returned by the runtime.

Settings

Member Visibility

On This Page

Constructors
Methods