@0xobelisk/sui-client 0.4.9

package/LICENSE

@@ -0,0 +1,92 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Obelisk Labs
+
+Licensed Work:        Obelisk Engine
+                      The Licensed Work is (c) 2023 Obelisk Labs
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -0,0 +1,284 @@
+# Obelisk Client SDK
+
+Obelisk 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.
+
+## Getting Started
+
+Before proceeding with the next steps, make sure you have deployed your own world contract via cli.
+
+When the world contract is deployed successfully, it will return a PackageId (the contract's ObjectId) and a WorldId (the World Store's ObjectId).
+
+### Data preparation
+
+We create a Project called Counter and declare sigleton schema called counter, which is of type `u64` and has an initial value of `0`.
+
+
+```typescript
+import { ObeliskConfig } from '@0xobelisk/sui-common';
+
+export const obeliskConfig = {
+  name: 'counter',
+  description: 'counter',
+  systems: ['counter_system'],
+  schemas: {
+    counter: {
+      valueType: 'u64',
+      defaultValue: 0,
+    },
+  },
+  sample_schema: 'u64',
+} as ObeliskConfig;
+```
+
+Through the CLI, we will generate the corresponding contract based on obelisk.config.ts At this point we need to write the system logic.
+
+```bash
+obelisk schemagen obelisk.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);
+    }
+}
+```
+
+Finally we deploy the complete contract to devnet
+
+
+```bash
+obelisk publish --network devnet --configPath obelisk.config.ts
+```
+
+We'll get the `packageId` and `worldId` on the command line.
+
+### Init Obelisk Client
+
+```typescript
+import { getMetadata, Obelisk, NetworkType } from "@0xobelisk/sui-client";
+
+const network = "devnet" as NetworkType
+const packageId = "0x804578b9eed47d461bba52c393cf148302819e2ba0a0f558356cc419b3e941ed"
+
+const metadata = await getMetadata(network, packageId);
+
+const obelisk = new Obelisk({
+    networkType: network,
+    packageId: packageId,
+    metadata: metadata,
+    secretKey: privkey
+});
+```
+
+### World Tx
+
+If you need to call a method in the system, you can do so using the `obelisk.tx.moudleName.funcName()` form.
+
+```typescript
+import { getMetadata, Obelisk, TransactionBlock } from "@0xobelisk/sui-client";
+
+const metadata = await getMetadata(network, packageId);
+
+const obelisk = new Obelisk({
+    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, true) as TransactionBlock;
+
+const response = await obelisk.signAndSendTxn(
+    new_tx
+)
+```
+
+### World Query
+
+#### 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()`.
+
+```typescript
+const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+const obelisk = new Obelisk({
+    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);
+```
+
+#### Get world
+
+Queries the Object information of worldId.
+
+```typescript
+    const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+    const obelisk = new Obelisk({
+        networkType: NETWORK,
+        packageId: PACKAGE_ID,
+        metadata: metadata,
+    });
+    const world_value = await obelisk.getWorld(WORLD_ID)
+```
+
+
+#### List schema names
+
+List all schema name in the world store.
+
+```typescript
+const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+const obelisk = new Obelisk({
+    networkType: NETWORK,
+    packageId: PACKAGE_ID,
+    metadata: metadata,
+});
+const schemaNames = await obelisk.listSchemaNames(
+  '0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0'
+);
+```
+
+
+#### Get entity
+
+Get the entity's data based on schema name and entity id(option).
+
+```typescript
+const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+const obelisk = new Obelisk({
+    networkType: NETWORK,
+    packageId: PACKAGE_ID,
+    metadata: metadata,
+});
+
+const worldId = "0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0";
+
+// get schema entity data
+const schemaName = "simple_schema"
+const entityId = "0x00000000000000000000000000000000000000000000000000000000000003ed"
+const entities = await obelisk.getEntity(
+    worldId,
+    schemaName,
+    entityId
+);
+
+// get singleton schema entity data
+const singletonSchemaName = "counter"
+const entities = await obelisk.getEntity(
+    worldId,
+    singletonSchemaName
+);
+
+```
+
+
+#### Contain entity
+
+Determine if the entity exists
+
+```typescript
+const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+const obelisk = new Obelisk({
+    networkType: NETWORK,
+    packageId: PACKAGE_ID,
+    metadata: metadata,
+});
+
+const worldId = "0x1541f3a2e7ac48e3e68e60bb97a7cee94e16316cc3f9043a9c0f5e6790ea3af0";
+
+// get schema entity data
+const schemaName = "simple_schema"
+const entityId = "0x00000000000000000000000000000000000000000000000000000000000003ed"
+const entities = await obelisk.containEntity(
+    worldId,
+    schemaName,
+    entityId
+);
+
+// get singleton schema entity data
+const singletonSchemaName = "counter"
+const entities = await obelisk.containEntity(
+    worldId,
+    singletonSchemaName
+);
+
+```
+
+#### Get owned objects
+
+Query all the objects under the current worldId that are owned by a certain address.
+
+```typescript
+const metadata = await getMetadata(NETWORK, PACKAGE_ID);
+const obelisk = new Obelisk({
+    networkType: NETWORK,
+    packageId: PACKAGE_ID,
+    metadata: metadata,
+});
+
+const owner = "0xfa99b5b0463fcfb7d0203c701a76da5eda21a96190eb1368ab36a437cc89195e";
+const owned_objects_value = await obelisk.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.
+
+
+```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);
+```
+

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from '@mysten/sui.js';
+export { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';
+export { BCS, getSuiMoveConfig } from '@mysten/bcs';
+export { Obelisk } from './obelisk';
+export { SuiAccountManager } from './libs/suiAccountManager';
+export { SuiTxBlock } from './libs/suiTxBuilder';
+export { SuiContractFactory } from './libs/suiContractFactory';
+export { loadMetadata } from './metadata';
+export type * from './types';