@0xobelisk/sui-client 0.5.27 → 0.5.28

package/README.md

@@ -1,78 +1,57 @@
 # Dubhe Client SDK
 
-Dubhe is client agnostic: any client -- a browser, a game engine, or an ios/android app -- can implement the synchronization protocol and a client-side cache to replicate Store tables, along with the necessary infrastructure to send transactions to the World.
-
-Currently we only support browsers, Node and the COCOS game engine.
+Dubhe is a client-agnostic SDK that supports various platforms including browsers, Node.js, and the COCOS game engine. It provides a simple interface to interact with your Sui Move contracts.
 
 ## Getting Started
 
-Before proceeding with the next steps, make sure you have deployed your own world contract via cli.
+### Prerequisites
 
-When the world contract is deployed successfully, it will return a PackageId (the contract's ObjectId) and a WorldId (the World Store's ObjectId).
+Before using the SDK, make sure you have:
 
-### Data preparation
+1. Created and deployed your contract using the Dubhe CLI
+2. Obtained the `packageId` after deployment
 
-We create a Project called Counter and declare sigleton schema called counter, which is of type `u64` and has an initial value of `0`.
+### Data Model Setup
 
+First, define your contract's configuration using `DubheConfig`:
 
 ```typescript
 import { DubheConfig } from '@0xobelisk/sui-common';
 
-export const obeliskConfig = {
+export const dubheConfig = {
   name: 'counter',
   description: 'counter',
-  systems: ['counter_system'],
+  systems: ['counter'],
   schemas: {
     counter: {
-      valueType: 'u64',
-      defaultValue: 0,
+      structure: {
+        value: 'StorageValue<u32>',
+      },
     },
   },
-  sample_schema: 'u64',
 } as DubheConfig;
 ```
 
-Through the CLI, we will generate the corresponding contract based on dubhe.config.ts At this point we need to write the system logic.
+Generate the contract code using CLI:
 
 ```bash
-obelisk schemagen dubhe.config.ts
+dubhe schemagen --configPath dubhe.config.ts
 ```
 
-The next step is simply to write the system file method.
-
-```rust
-// contracts/counter/system/counter_system.move
-module counter::counter_system {
-    use counter::world::World;
-    use counter::counter_schema;
-
-    public entry fun inc(world: &mut World){
-        let value = counter_schema::get(world) + 1;
-        counter_schema::set(world,value);
-    }
-}
-```
+### Initializing the Client
 
-Finally we deploy the complete contract to devnet
+There are two ways to initialize the Dubhe client:
 
-
-```bash
-obelisk publish --network devnet --configPath dubhe.config.ts
-```
-
-We'll get the `packageId` and `worldId` on the command line.
-
-### Init Dubhe Client
+1. Using dynamic metadata loading:
 
 ```typescript
-import { getMetadata, Dubhe, NetworkType } from "@0xobelisk/sui-client";
-
-const network = "devnet" as NetworkType
-const packageId = "0x804578b9eed47d461bba52c393cf148302819e2ba0a0f558356cc419b3e941ed"
+import { loadMetadata, Dubhe, NetworkType } from "@0xobelisk/sui-client";
 
-const metadata = await getMetadata(network, packageId);
+const network = "devnet" as NetworkType;
+const packageId = "YOUR_PACKAGE_ID";
 
-const obelisk = new Dubhe({
+const metadata = await loadMetadata(network, packageId);
+const dubhe = new Dubhe({
     networkType: network,
     packageId: packageId,
     metadata: metadata,
@@ -80,205 +59,119 @@ const obelisk = new Dubhe({
 });
 ```
 
-### World Tx
-
-If you need to call a method in the system, you can do so using the `obelisk.tx.moudleName.funcName()` form.
+2. Using pre-saved metadata (recommended for better performance):
 
 ```typescript
-import { getMetadata, Dubhe, TransactionBlock } from "@0xobelisk/sui-client";
-
-const metadata = await getMetadata(network, packageId);
+import metadata from './metadata.json';
 
-const obelisk = new Dubhe({
+const dubhe = new Dubhe({
     networkType: network,
     packageId: packageId,
     metadata: metadata,
     secretKey: privkey
 });
-
-// Initiate transactions through the account set up by obelisk
-const tx = new TransactionBlock()
-
-const world = tx.pure(WORLD_ID)
-const params = [
-    world,
-]
-
-const res_tx = await obelisk.tx.counter_system.inc(tx, params)
-
-// If you want to encapsulate the TransactionBlock
-const tx = new TransactionBlock()
-const world = tx.pure(WORLD_ID)
-const params = [
-    world,
-]
-// By isolating the signature from the transactionBlock construction in this way,
-// the front-end wallet plugin can signAndSend() directly to the transactionBlock,
-// facilitating front-end interaction.
-const new_tx = await obelisk.tx.counter_system.inc(tx, params, undefined, true) as TransactionBlock;
-
-const response = await obelisk.signAndSendTxn(
-    new_tx
-)
 ```
 
-### World Query
+### Executing Transactions
 
-#### Query public contract view func
-
-If your system method provides a method with no modification status and a return, then you can query it via `obelisk.query.moudleName.funcName()`.
+To call contract methods:
 
 ```typescript
-const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-const obelisk = new Dubhe({
-    networkType: NETWORK,
-    packageId: PACKAGE_ID,
-    metadata: metadata,
-});
-
-const tx = new TransactionBlock()
-const world = tx.pure(WORLD_ID)
-const params = [
-    world,
-]
-const query_value = await obelisk.query.counter_system.get(tx, params);
-```
+import { Transaction } from "@0xobelisk/sui-client";
 
-#### Get world
+// Create transaction
+const tx = new Transaction();
+const params = [/* your parameters */];
 
-Queries the Object information of worldId.
+// Execute transaction
+const response = await dubhe.tx.counter_system.inc(tx, params);
 
-```typescript
-    const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-    const obelisk = new Dubhe({
-        networkType: NETWORK,
-        packageId: PACKAGE_ID,
-        metadata: metadata,
-    });
-    const world_value = await obelisk.getWorld(WORLD_ID)
+// For wallet integration
+await dubhe.tx.counter_system.inc(tx, params, undefined, true);
+const response = await dubhe.signAndSendTxn(tx);
 ```
 
+### Querying Data
 
-#### List schema names
-
-List all schema name in the world store.
+To query contract state:
 
 ```typescript
-const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-const obelisk = new Dubhe({
-    networkType: NETWORK,
-    packageId: PACKAGE_ID,
-    metadata: metadata,
-});
-const schemaNames = await obelisk.listSchemaNames(
-  '0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0'
-);
-```
+const tx = new Transaction();
+const params = [/* your parameters */];
+const result = await dubhe.query.counter_system.get(tx, params);
 
+// For BCS encoded results
+const decodedData = dubhe.view(result);
+```
 
-#### Get entity
+### BCS Data Decoding
 
-Get the entity's data based on schema name and entity id(option).
+The SDK provides a `view()` method to decode BCS-encoded return values from contract queries.
 
-```typescript
-const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-const obelisk = new Dubhe({
-    networkType: NETWORK,
-    packageId: PACKAGE_ID,
-    metadata: metadata,
-});
+#### Supported Types
 
-const worldId = "0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0";
+- Basic types (u8, u16, u32, u64, u128, u256)
+- Boolean
+- String
+- Vector
+- Struct
+- Option
+- Custom objects
 
-// get schema entity data
-const schemaName = "simple_schema"
-const entityId = "0x00000000000000000000000000000000000000000000000000000000000003ed"
-const entities = await obelisk.getEntity(
-    worldId,
-    schemaName,
-    entityId
-);
+#### Example with Complex Types
 
-// get singleton schema entity data
-const singletonSchemaName = "counter"
-const entities = await obelisk.getEntity(
-    worldId,
-    singletonSchemaName
-);
+```typescript
+// Example contract return type
+struct GameState {
+    score: u64,
+    player_name: String,
+    is_active: bool,
+    items: vector<Item>
+}
 
+// Query and decode
+const tx = new Transaction();
+const result = await dubhe.query.game_system.get_state(tx, params);
+const decodedState = dubhe.view(result);
 ```
 
+#### Known Limitations
 
-#### Contain entity
+⚠️ **Important Note**:
 
-Determine if the entity exists
+1. The current implementation cannot automatically decode enum types due to limitations in Sui metadata.
+2. Some complex nested structures might require additional handling.
 
-```typescript
-const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-const obelisk = new Dubhe({
-    networkType: NETWORK,
-    packageId: PACKAGE_ID,
-    metadata: metadata,
-});
+### Entity Key Generation
 
-const worldId = "0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0";
+Dubhe provides three methods for generating entity keys:
 
-// get schema entity data
-const schemaName = "simple_schema"
-const entityId = "0x00000000000000000000000000000000000000000000000000000000000003ed"
-const entities = await obelisk.containEntity(
-    worldId,
-    schemaName,
-    entityId
-);
+```typescript
+// From object ID
+const objectKey = await dubhe.entity_key_from_object(objectId);
 
-// get singleton schema entity data
-const singletonSchemaName = "counter"
-const entities = await obelisk.containEntity(
-    worldId,
-    singletonSchemaName
-);
+// From string data
+const bytesKey = await dubhe.entity_key_from_bytes('hello');
 
+// From number
+const numberKey = await dubhe.entity_key_from_u256(123);
 ```
 
-#### Get owned objects
+### Query Owned Objects
 
-Query all the objects under the current worldId that are owned by a certain address.
+To query objects owned by a specific address:
 
 ```typescript
-const metadata = await getMetadata(NETWORK, PACKAGE_ID);
-const obelisk = new Dubhe({
-    networkType: NETWORK,
-    packageId: PACKAGE_ID,
-    metadata: metadata,
-});
-
 const owner = "0xfa99b5b0463fcfb7d0203c701a76da5eda21a96190eb1368ab36a437cc89195e";
-const owned_objects_value = await obelisk.getOwnedObjects(owner);
+const ownedObjects = await dubhe.getOwnedObjects(owner);
 ```
 
-### About entity key
-
-You can customize how the key is generated in the system, but I recommend that you generate the entity key using the user's address or objectId as the associative data, as this will help you associate the generated entity with address/objectId. This will help you associate the generated entity with the user's address, and then you can quickly determine the creator of the entity by the user's address or objectId.
-
-We provide three ways to convert entity keys, and of course you are welcome to contribute more entity key specifications.
+## Best Practices
 
+1. Use pre-saved metadata for better performance in production
+2. Implement proper error handling for BCS decoding
+3. Consider the limitations of enum type handling when designing your contract return types
 
-```typescript
-// Create key based on objectId.
-// You can use the user's address as the entity key, 
-// or you can use the Id of an object as the entity key.
-//
-// For example: using the objectId of the NFT as the key, 
-// you can set the owner of the nft as the owner of the accessed entity.
-let objectAddress = await obelisk.entity_key_from_object(
-    '0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0'
-);
-
-// hexAddress(keccak256(inputStringData))
-let bytesAddress = await obelisk.entity_key_from_bytes('hello');
-
-// hexAddress(inputNumberData)
-let numberAddress = await obelisk.entity_key_from_u256(123);
-```
+## Support
 
+For more information or support, please visit our GitHub repository or join our community channels.

package/dist/dubhe.d.ts

@@ -39,7 +39,7 @@ export declare class Dubhe {
     get query(): MapMoudleFuncQuery;
     get tx(): MapMoudleFuncTx;
     get object(): MapObjectStruct;
-    view(dryResult: DevInspectResults): any[] | undefined;
+    view(dryResult: DevInspectResults): any[];
     /**
      * if derivePathParams is not provided or mnemonics is empty, it will return the keypair.
      * else:

package/dist/errors/index.d.ts

@@ -0,0 +1,7 @@
+export declare class ContractDataParsingError extends Error {
+    readonly errorType: string;
+    readonly functionName: string;
+    readonly moduleAddress: string;
+    readonly errorMessage: string;
+    constructor(dryResult: any);
+}

package/dist/index.js

@@ -946,6 +946,31 @@ function numberToAddressHex(num) {
 
 // src/dubhe.ts
 var import_bcs2 = require("@mysten/bcs");
+
+// src/errors/index.ts
+var ContractDataParsingError = class extends Error {
+  constructor(dryResult) {
+    const error = dryResult?.effects?.status?.error || "";
+    const functionMatch = error ? error.match(/function_name: Some\("([^"]+)"\)/) : null;
+    const moduleMatch = error ? error.match(/address: ([a-fA-F0-9]+)/) : null;
+    const functionName = functionMatch ? functionMatch[1] : "unknown";
+    const moduleAddress = moduleMatch ? "0x" + moduleMatch[1] : "unknown";
+    const errorMessage = dryResult.error ? dryResult.error : "UNKNOWN_ERROR";
+    const message = [
+      `
+- Function: ${functionName}`,
+      `- Module Address: ${moduleAddress}`,
+      `- Error Message: ${errorMessage}`
+    ].join("\n");
+    super(message);
+    this.errorType = "ContractDataParsingError";
+    this.functionName = functionName;
+    this.moduleAddress = moduleAddress;
+    this.errorMessage = errorMessage;
+  }
+};
+
+// src/dubhe.ts
 function isUndefined(value) {
   return value === void 0;
 }
@@ -1376,7 +1401,7 @@ var Dubhe = class {
       }
       return returnValues;
     } else {
-      return void 0;
+      throw new ContractDataParsingError(dryResult);
     }
   }
   /**