@mysten/sui-groups

TypeScript SDK for permissioned groups on Sui. Create and manage groups with fine-grained, on-chain permissions using the sui_groups Move package.

Installation

npm install @mysten/sui-groups

Peer dependencies: @mysten/sui, @mysten/bcs

Quick Start

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { suiGroups } from '@mysten/sui-groups';

// Create a Sui client extended with groups
const client = new SuiGrpcClient({ network: 'testnet' }).$extend(
    suiGroups({
        // The witness type from your extending Move package
        witnessType: '0xYOUR_PACKAGE::module::WITNESS',
    }),
);

// Add members with permissions
await client.groups.addMembers({
    signer,
    groupId: '0x...',
    members: [
        {
            address: '0xalice...',
            permissions: ['0xYOUR_PACKAGE::module::Reader', '0xYOUR_PACKAGE::module::Writer'],
        },
        { address: '0xbob...', permissions: ['0xYOUR_PACKAGE::module::Reader'] },
    ],
});

// Grant / revoke permissions
await client.groups.grantPermission({
    signer,
    groupId: '0x...',
    member: '0xalice...',
    permissionType: '0xYOUR_PACKAGE::module::Admin',
});
await client.groups.revokePermission({
    signer,
    groupId: '0x...',
    member: '0xbob...',
    permissionType: '0xYOUR_PACKAGE::module::Writer',
});

// Remove a member
await client.groups.removeMember({ signer, groupId: '0x...', member: '0xbob...' });

// Pause / unpause a group
await client.groups.pause({ signer, groupId: '0x...' });
await client.groups.unpause({ signer, groupId: '0x...', unpauseCapId: '0x...' });

Client Extension Pattern

The SDK uses Sui's client extension system. Call $extend(suiGroups(...)) on any Sui client (SuiGrpcClient, SuiGraphQLClient, etc.) to add the .groups property:

const client = suiClient.$extend(
    suiGroups({
        witnessType: '0xYOUR_PACKAGE::module::WITNESS',
        // Optional: override package config for localnet/devnet
        packageConfig: { originalPackageId: '0x...', latestPackageId: '0x...' },
    }),
);

client.groups; // SuiGroupsClient instance
client.groups.tx; // Transaction builders (returns Transaction, doesn't execute)
client.groups.call; // Low-level Move call builders
client.groups.view; // Read-only queries
client.groups.bcs; // BCS parsing utilities

API

Top-Level Methods

These sign, execute, and wait for the transaction:

Method	Description
`addMembers()`	Add members with permissions (idempotent)
`grantPermission()`	Grant a permission (adds the member if they're new)
`grantPermissions()`	Grant multiple permissions in one transaction
`revokePermission()`	Revoke a permission (removes member if last one)
`revokePermissions()`	Revoke multiple permissions in one transaction
`removeMember()`	Remove a member entirely
`pause()`	Pause the group, receive an `UnpauseCap`
`unpause()`	Unpause the group by consuming the `UnpauseCap`

Transaction Builders (`client.groups.tx`)

Same methods as above, but return a Transaction object without executing. Useful for composing with other transactions.

License

Apache-2.0