@aboutcircles/sdk 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# @aboutcircles/sdk
+
+Simplified Circles SDK for non-crypto users with a low entrance barrier. This package provides user-friendly abstractions over the Circles protocol, making it easier for developers to build applications without deep blockchain knowledge.
+
+## Overview
+
+The SDK package provides two main models:
+
+1. **Sdk** - Main entry point for interacting with Circles
+2. **Avatar** - Represents a Circles identity (human, organization, or group)
+
+## Installation
+
+```bash
+npm install @aboutcircles/sdk
+# or
+bun add @aboutcircles/sdk
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Sdk } from '@aboutcircles/sdk';
+
+// Create SDK instance with default configuration (Gnosis Chain)
+const sdk = new Sdk();
+
+// Or with custom configuration
+import { circlesConfig } from '@aboutcircles/sdk-core';
+const sdk = new Sdk(circlesConfig[100], 'https://custom-rpc.com');
+```
+
+### Working with Avatars
+
+```typescript
+// Get an avatar
+const avatar = await sdk.getAvatar('0xAvatarAddress');
+
+// Access avatar properties
+console.log(avatar.address);
+console.log(avatar.avatarInfo);
+```
+
+### Registration (Not Yet Implemented)
+
+```typescript
+// Register as a human
+const avatar = await sdk.register.asHuman('0xInviterAddress', {
+  name: 'Alice',
+  description: 'Developer'
+});
+
+// Register as an organization
+const avatar = await sdk.register.asOrganization({
+  name: 'My Organization',
+  description: 'A great organization'
+});
+
+// Register as a group
+const avatar = await sdk.register.asGroup('0xMintPolicyAddress', {
+  name: 'My Group',
+  symbol: 'MGP',
+  description: 'A collaborative group'
+});
+```
+
+### Avatar Methods
+
+The Avatar class provides methods for common Circles operations:
+
+#### Balance Methods
+
+```typescript
+// Get total balance
+const total = await avatar.balances.getTotal();
+
+// Get detailed token balances
+const balances = await avatar.balances.getDetailed();
+
+// Get gas token balance
+const gasBalance = await avatar.balances.getGasToken();
+```
+
+#### Transfer Methods
+
+```typescript
+// Simple direct transfer
+await avatar.transfer.direct('0xRecipient', 100);
+
+// Advanced transfer with options
+await avatar.transfer.advanced('0xRecipient', 100, {
+  token: '0xTokenAddress',
+  useWrappedBalances: true
+});
+
+// Get maximum transferable amount
+const maxAmount = await avatar.transfer.getMaxAmount('0xRecipient');
+```
+
+#### Trust Methods
+
+```typescript
+// Add trust
+await avatar.trust.add('0xTrustee');
+
+// Remove trust
+await avatar.trust.remove('0xTrustee');
+
+// Check trust status
+const isTrusting = await avatar.trust.isTrusting('0xOtherAvatar');
+const isTrustedBy = await avatar.trust.isTrustedBy('0xOtherAvatar');
+
+// Get all trust relations
+const trustRelations = await avatar.trust.getAll();
+```
+
+#### Personal Token Methods
+
+```typescript
+// Get available minting amount
+const available = await avatar.personalToken.getAvailableAmount();
+
+// Mint personal tokens
+await avatar.personalToken.mint();
+
+// Stop minting (irreversible)
+await avatar.personalToken.stop();
+```
+
+#### Profile Methods
+
+```typescript
+// Get profile
+const profile = await avatar.profile.get();
+
+// Update profile
+const cid = await avatar.profile.update({
+  name: 'Alice',
+  description: 'Updated description'
+});
+
+// Update metadata (CID only)
+await avatar.profile.updateMetadata('QmNewCID');
+
+// Register short name
+await avatar.profile.registerShortName(123);
+```
+
+#### Group Methods
+
+```typescript
+// Mint group tokens
+await avatar.groupToken.mint(
+  '0xGroupAddress',
+  ['0xCollateral1', '0xCollateral2'],
+  [BigInt(100), BigInt(200)],
+  new Uint8Array()
+);
+
+// Redeem collateral
+await avatar.groupToken.redeem(
+  '0xGroupAddress',
+  ['0xCollateral1'],
+  [BigInt(100)]
+);
+
+// Get group properties
+const owner = await avatar.group.properties.owner();
+const mintHandler = await avatar.group.properties.mintHandler();
+
+// Set group properties
+await avatar.group.setProperties.owner('0xNewOwner');
+```
+
+#### Wrapping Methods
+
+```typescript
+// Wrap as demurraged ERC20
+const tokenAddress = await avatar.wrap.asDemurraged('0xAvatarAddress', BigInt(100));
+
+// Wrap as inflationary ERC20
+const tokenAddress = await avatar.wrap.asInflationary('0xAvatarAddress', BigInt(100));
+
+// Unwrap tokens
+await avatar.wrap.unwrapDemurraged('0xTokenAddress', BigInt(100));
+await avatar.wrap.unwrapInflationary('0xAvatarAddress', BigInt(100));
+```
+
+### Profile Management
+
+```typescript
+// Get profile by CID
+const profile = await sdk.profiles.get('QmProfileCID');
+
+// Create or update profile
+await sdk.profiles.createOrUpdate({
+  name: 'Alice',
+  description: 'Developer'
+});
+```
+
+## Implementation Status
+
+⚠️ **Note**: This package is currently a skeleton implementation. Most methods throw "Not yet implemented" errors and are marked with TODO comments. The purpose is to establish the API surface for future implementation.
+
+### Implemented Features
+
+- ✅ SDK initialization with configuration
+- ✅ Avatar retrieval (getAvatar)
+- ✅ Profile retrieval by CID (via profiles package)
+
+### Not Yet Implemented
+
+Most features are marked with TODO and will throw errors:
+
+- Registration methods (asHuman, asOrganization, asGroup)
+- Balance operations
+- Transfer operations
+- Trust operations
+- Personal token minting
+- Profile updates
+- Group operations
+- Token wrapping
+- Event streaming
+
+## Architecture
+
+The SDK package wraps and simplifies the following packages:
+
+- `@aboutcircles/sdk-core` - Core contract interactions
+- `@aboutcircles/sdk-rpc` - RPC client for Circles-specific methods
+- `@aboutcircles/sdk-profiles` - Profile management
+- `@aboutcircles/sdk-types` - TypeScript type definitions
+- `@aboutcircles/sdk-utils` - Utility functions
+
+## Contributing
+
+To implement a method:
+
+1. Remove the "TODO" comment
+2. Replace the `throw new Error('not yet implemented')` with actual implementation
+3. Use the underlying packages (core, rpc, profiles, etc.) to implement functionality
+4. Add tests and update documentation
+
+## License
+
+MIT

package/dist/Sdk.d.ts

@@ -0,0 +1,282 @@
+import type { Address, CirclesConfig, ContractRunner, Profile, TokenBalance, SortOrder } from '@aboutcircles/sdk-types';
+import type { GroupTokenHolderRow } from '@aboutcircles/sdk-rpc';
+import { Core } from '@aboutcircles/sdk-core';
+import { CirclesRpc, PagedQuery } from '@aboutcircles/sdk-rpc';
+import { HumanAvatar, OrganisationAvatar, BaseGroupAvatar } from './avatars';
+import type { GroupType } from '@aboutcircles/sdk-types';
+import type { CirclesData } from './types';
+/**
+ * Simplified Circles SDK
+ * Provides a user-friendly API for non-crypto users with low entrance barrier
+ *
+ * @example
+ * ```typescript
+ * const sdk = new Sdk();
+ *
+ * // Register as a human
+ * const avatar = await sdk.register.asHuman('0xInviterAddress', {
+ *   name: 'Alice',
+ *   description: 'Developer'
+ * });
+ *
+ * // Get an avatar
+ * const avatar = await sdk.getAvatar('0xAvatarAddress');
+ *
+ * // Transfer tokens
+ * await avatar.transfer.direct('0xRecipient', 100);
+ *
+ * // Mint personal tokens
+ * await avatar.personalToken.mint();
+ * ```
+ */
+export declare class Sdk {
+    readonly circlesConfig: CirclesConfig;
+    readonly contractRunner?: ContractRunner;
+    readonly senderAddress?: Address;
+    readonly core: Core;
+    readonly rpc: CirclesRpc;
+    private readonly profilesClient;
+    readonly data: CirclesData;
+    /**
+     * Create a new Sdk instance
+     *
+     * @param config Circles configuration (defaults to Gnosis Chain mainnet)
+     * @param contractRunner Optional contract runner for executing transactions
+     * @throws Error if contractRunner is provided but doesn't support sendTransaction or has no address
+     */
+    constructor(config?: CirclesConfig, contractRunner?: ContractRunner);
+    /**
+     * Get an avatar by address
+     * Automatically detects the avatar type and returns the appropriate avatar instance
+     * @returns HumanAvatar, OrganisationAvatar, or BaseGroupAvatar depending on type
+     */
+    getAvatar(avatarAddress: Address): Promise<HumanAvatar | OrganisationAvatar | BaseGroupAvatar>;
+    /**
+     * Registration methods for creating new Circles identities
+     */
+    readonly register: {
+        /**
+         * Register as a human in the Circles ecosystem
+         *
+         * This function:
+         * 1. Checks for pending invitations from inviters in the InvitationEscrow
+         * 2. If invitations exist, redeems one to claim escrowed tokens
+         * 3. Otherwise, checks if the specified inviter has enough unwrapped CRC
+         * 4. Creates and uploads profile data to IPFS
+         * 5. Registers the human with the profile CID
+         * 6. Returns a HumanAvatar instance for the registered account
+         *
+         * Requirements:
+         * - Contract runner must be configured to execute transactions
+         * - Either: pending invitations from inviters, OR inviter has 96+ CRC unwrapped
+         *
+         * @param inviter Address of the inviting avatar (fallback if no invitations found)
+         * @param profile Profile data with name, description, etc.
+         * @returns HumanAvatar instance for the newly registered human
+         *
+         * @example
+         * ```typescript
+         * const avatar = await sdk.register.asHuman('0xInviter', {
+         *   name: 'Alice',
+         *   description: 'Developer'
+         * });
+         * ```
+         */
+        asHuman: (inviter: Address, profile: Profile | string) => Promise<HumanAvatar>;
+        /**
+         * Register as an organization
+         * Organizations can participate in Circles without minting personal tokens
+         * and do not require invitations to register
+         *
+         * @param profile Profile data for the organization or CID string
+         * @returns OrganisationAvatar instance for the newly registered organization
+         *
+         * @example
+         * ```typescript
+         * const orgAvatar = await sdk.register.asOrganization({
+         *   name: 'My Organization',
+         *   description: 'A Circles organization'
+         * });
+         * ```
+         */
+        asOrganization: (profile: Profile | string) => Promise<OrganisationAvatar>;
+        /**
+         * Register a base group
+         * Creates a new base group using the BaseGroupFactory and registers it in the Circles ecosystem
+         *
+         * @param owner The address that will own the newly created BaseGroup
+         * @param service The address of the service for the new BaseGroup
+         * @param feeCollection The address of the fee collection for the new BaseGroup
+         * @param initialConditions An array of initial condition addresses
+         * @param name The group name (must be 19 characters or fewer)
+         * @param symbol The group symbol (e.g., 'MYG')
+         * @param profile Profile data (name, description, images, etc.) or CID string
+         * @returns BaseGroupAvatar instance for the newly registered group
+         *
+         * @example
+         * ```typescript
+         * const groupAvatar = await sdk.register.asGroup(
+         *   '0xOwnerAddress',
+         *   '0xServiceAddress',
+         *   '0xFeeCollectionAddress',
+         *   [], // initial conditions
+         *   'My Group', // name
+         *   'MYG', // symbol
+         *   {
+         *     name: 'My Group',
+         *     description: 'A Circles base group'
+         *   }
+         * );
+         * ```
+         */
+        asGroup: (owner: Address, service: Address, feeCollection: Address, initialConditions: Address[], name: string, symbol: string, profile: Profile | string) => Promise<BaseGroupAvatar>;
+    };
+    /**
+     * Profile management methods
+     */
+    readonly profiles: {
+        /**
+         * Create and pin a profile to IPFS
+         * @param profile Profile data or CID string
+         * @returns CID of the pinned profile
+         */
+        create: (profile: Profile) => Promise<string>;
+        /**
+         * Get a profile by CID
+         * @param cid Content identifier
+         * @returns Profile data or undefined if not found
+         */
+        get: (cid: string) => Promise<Profile | undefined>;
+    };
+    /**
+     * Token utilities
+     */
+    readonly tokens: {
+        /**
+         * Get an inflationary wrapper for a token
+         * @param address Avatar address
+         * @returns The ERC20 inflationary wrapper address, or zero address if not deployed
+         */
+        getInflationaryWrapper: (address: Address) => Promise<Address>;
+        /**
+         * Get a demurraged wrapper for a token
+         * @param address Avatar address
+         * @returns The ERC20 demurraged wrapper address, or zero address if not deployed
+         */
+        getDemurragedWrapper: (address: Address) => Promise<Address>;
+        /**
+         * Get token holders for a specific token address with pagination
+         * @param tokenAddress The token address to query holders for
+         * @param limit Maximum number of results per page (default: 100)
+         * @param sortOrder Sort order for results (default: 'DESC' - highest balance first)
+         * @returns PagedQuery instance for token holders
+         *
+         * @example
+         * ```typescript
+         * const holdersQuery = sdk.tokens.getHolders('0x42cedde51198d1773590311e2a340dc06b24cb37', 10);
+         *
+         * while (await holdersQuery.queryNextPage()) {
+         *   const page = holdersQuery.currentPage!;
+         *   console.log(`Found ${page.size} holders`);
+         *   page.results.forEach(holder => {
+         *     console.log(`${holder.account}: ${holder.demurragedTotalBalance}`);
+         *   });
+         * }
+         * ```
+         */
+        getHolders: (tokenAddress: Address, limit?: number, sortOrder?: SortOrder) => PagedQuery<import("@aboutcircles/sdk-types").TokenHolder>;
+    };
+    /**
+     * Group utilities
+     */
+    readonly groups: {
+        /**
+         * Get the type of a group
+         * @param avatar Group avatar address
+         * @returns Group type or undefined if not a group
+         */
+        getType: (avatar: Address) => Promise<GroupType | undefined>;
+        /**
+         * Get all members of a specific group using cursor-based pagination
+         *
+         * Returns a PagedQuery instance for iterating through members of the specified group,
+         * including membership details such as expiry time and when the membership was created.
+         *
+         * @param groupAddress The address of the group to query members for
+         * @param limit Number of members per page (default: 100)
+         * @param sortOrder Sort order for results (default: 'DESC')
+         * @returns PagedQuery instance for iterating through group members
+         *
+         * @example
+         * ```typescript
+         * const query = sdk.groups.getMembers('0xGroupAddress...');
+         *
+         * // Get first page
+         * await query.queryNextPage();
+         * console.log(`${query.currentPage.size} members in the group`);
+         *
+         * // Iterate through all members
+         * while (await query.queryNextPage()) {
+         *   query.currentPage.results.forEach(membership => {
+         *     console.log(`Member: ${membership.member}`);
+         *     console.log(`Expiry: ${new Date(membership.expiryTime * 1000).toLocaleDateString()}`);
+         *   });
+         * }
+         * ```
+         */
+        getMembers: (groupAddress: Address, limit?: number, sortOrder?: "ASC" | "DESC") => PagedQuery<import("@aboutcircles/sdk-types").GroupMembershipRow>;
+        /**
+         * Get collateral tokens in a group's treasury
+         *
+         * This convenience method fetches the treasury address of a group and returns
+         * all token balances held in the treasury.
+         *
+         * @param groupAddress The address of the group
+         * @returns Array of token balances in the treasury
+         *
+         * @example
+         * ```typescript
+         * // Get collateral tokens in a group treasury
+         * const collateral = await sdk.groups.getCollateral('0xGroupAddress...');
+         *
+         * collateral.forEach(balance => {
+         *   console.log(`Token: ${balance.tokenAddress}`);
+         *   console.log(`Balance: ${balance.circles} CRC`);
+         * });
+         * ```
+         */
+        getCollateral: (groupAddress: Address) => Promise<TokenBalance[]>;
+        /**
+         * Get all holders of a group token using cursor-based pagination
+         *
+         * Returns all avatars that hold the specified group token, ordered by balance (highest first),
+         * including balance amounts and ownership fractions.
+         *
+         * @param groupAddress The address of the group token
+         * @param limit Maximum number of holders to return (default: 100)
+         * @returns PagedQuery instance for iterating through group token holders
+         *
+         * @example
+         * ```typescript
+         * // Get all holders of a group token
+         * const query = sdk.groups.getHolders('0xGroupAddress...');
+         *
+         * // Get first page (ordered by balance DESC)
+         * await query.queryNextPage();
+         * console.log(`${query.currentPage.size} holders of this group token`);
+         *
+         * // Iterate through all holders
+         * while (await query.queryNextPage()) {
+         *   query.currentPage.results.forEach(holder => {
+         *     const balanceInCrc = Number(holder.totalBalance) / 1e18;
+         *     console.log(`Holder: ${holder.holder}`);
+         *     console.log(`Balance: ${balanceInCrc.toFixed(2)} CRC`);
+         *     console.log(`Ownership: ${(holder.fractionOwnership * 100).toFixed(2)}%`);
+         *   });
+         * }
+         * ```
+         */
+        getHolders: (groupAddress: Address, limit?: number) => PagedQuery<GroupTokenHolderRow>;
+    };
+}
+//# sourceMappingURL=Sdk.d.ts.map

package/dist/Sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sdk.d.ts","sourceRoot":"","sources":["../src/Sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,cAAc,EACd,OAAO,EAEP,YAAY,EACZ,SAAS,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAiB,IAAI,EAAkC,MAAM,wBAAwB,CAAC;AAE7F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAI7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,qBAAa,GAAG;IACd,SAAgB,aAAa,EAAE,aAAa,CAAC;IAC7C,SAAgB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChD,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxC,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,GAAG,EAAE,UAAU,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAE1C,SAAgB,IAAI,EAAE,WAAW,CAU/B;IAEF;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkC,EAAE,cAAc,CAAC,EAAE,cAAc;IAsBvF;;;;OAIG;IACG,SAAS,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,GAAG,kBAAkB,GAAG,eAAe,CAAC;IAsBpG;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;2BAEQ,OAAO,WACP,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,WAAW,CAAC;QAqEvB;;;;;;;;;;;;;;;WAeG;kCAC6B,OAAO,GAAG,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAAC;QAqD9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;yBAEM,OAAO,WACL,OAAO,iBACD,OAAO,qBACH,OAAO,EAAE,QACtB,MAAM,UACJ,MAAM,WACL,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,eAAe,CAAC;MAsF3B;IAEF;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,MAAM,CAAC;QAIjD;;;;WAIG;mBACc,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;MAGtD;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0CACqC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIlE;;;;WAIG;wCACmC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;WAmBG;mCAEa,OAAO,UACd,MAAM,cACF,SAAS;MAItB;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2BG;mCAEa,OAAO,UACd,MAAM,cACF,KAAK,GAAG,MAAM;QAK3B;;;;;;;;;;;;;;;;;;;WAmBG;sCACiC,OAAO,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QAcrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;mCACwB,OAAO,UAAS,MAAM,KAAS,UAAU,CAAC,mBAAmB,CAAC;MAGzF;CACH"}