@d9-network/ink 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,82 @@
+# @d9-network/ink
+
+Type-safe SDK for interacting with ink! smart contracts on the D9 blockchain network.
+
+## Installation
+
+```bash
+npm install @d9-network/ink
+# or
+bun add @d9-network/ink
+# or
+pnpm add @d9-network/ink
+```
+
+## Quick Start
+
+```typescript
+import { createD9InkSdk } from "@d9-network/ink";
+import { usdt } from "@d9-network/spec"; // Contract descriptor
+
+// Create SDK instance
+const sdk = await createD9InkSdk({
+  endpoint: "wss://mainnet.d9network.xyz:40300",
+});
+
+// Create contract instance
+const contract = sdk.createContract(usdt, "cXYZ...contractAddress");
+
+// Query contract state
+const result = await contract.query("PSP22::balance_of", {
+  origin: "cXYZ...yourAddress",
+  args: { owner: "cXYZ...targetAddress" },
+});
+
+if (result.success) {
+  console.log("Balance:", result.value);
+}
+```
+
+## Features
+
+- **Type-safe contract interactions**: Full TypeScript inference for message parameters and return types
+- **Automatic gas estimation**: Dry-run execution before submitting transactions
+- **AccountId with D9 prefix**: All addresses automatically use D9 SS58 prefix (9)
+- **Event parsing**: Type-safe decoding of contract events
+- **Comprehensive error handling**: Detailed error types for debugging
+
+## API Overview
+
+### SDK Creation
+
+| Export                | Description                |
+| --------------------- | -------------------------- |
+| `createD9InkSdk`      | Create ink SDK instance    |
+| `createD9InkContract` | Create individual contract |
+
+### Encoding/Decoding
+
+| Export                     | Description                 |
+| -------------------------- | --------------------------- |
+| `encodeCall`               | Encode contract call        |
+| `decodeContractCallResult` | Decode contract call result |
+| `InkCodecs`                | Pre-defined SCALE codecs    |
+
+### Error Types
+
+| Export          | Description           |
+| --------------- | --------------------- |
+| `ContractError` | Base contract error   |
+| `DecodeError`   | Result decoding error |
+| `LangError`     | ink! language error   |
+| `NetworkError`  | RPC/WebSocket error   |
+
+## Documentation
+
+For complete documentation, examples, and API reference, visit:
+
+- [D9 SDK Documentation](https://docs.d9network.xyz/docs/sdk/ink/overview)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -11,10 +11,25 @@ let rxjs = require("rxjs");
 /**
 * D9 Network constants
 */
-/** D9 SS58 address prefix */
+/**
+* D9 SS58 address prefix.
+*
+* SS58 is the address format used by Substrate-based chains. Each chain has a unique
+* prefix that determines the address format and ensures addresses are network-specific.
+*
+* D9 uses prefix 9, which produces addresses starting with 'c' or 'd'.
+*
+* This prefix is automatically applied to all AccountId encoding/decoding operations
+* in the SDK, including:
+* - Contract call parameter encoding
+* - Result decoding
+* - Event parsing
+*
+* @see https://github.com/paritytech/ss58-registry for the full SS58 registry
+*/
 const D9_SS58_PREFIX = 9;
 /** D9 token decimals */
-const D9_DECIMALS = 2;
+const D9_DECIMALS = 12;
 /** D9 token symbol */
 const D9_SYMBOL = "D9";
 /** USDT token decimals */
@@ -152,13 +167,6 @@ function decodeContractCallResult(result) {
 	};
 }
 /**
-* Legacy function - decode and return just the exec result data.
-* @deprecated Use decodeContractCallResult for full information
-*/
-function decodeResult(result) {
-	return decodeContractCallResult(result).data;
-}
-/**
 * Unwrap the inner value from Result<T, LangError> by checking the variant byte.
 *
 * Ink contracts wrap their return values in Result<T, LangError>.
@@ -1094,6 +1102,43 @@ function isErrorType(error, type) {
 //#endregion
 //#region src/contract.ts
 /**
+* Decode response data using papi's value codec with proper result unwrapping.
+* This helper handles the common pattern of wrapping inner data in an Ok variant
+* and extracting the actual value from papi's decoded result.
+*
+* @param innerData - The raw response bytes to decode
+* @param codec - The papi codec with value.dec method
+* @param method - Method name for error context
+* @returns Decoded value or error
+*/
+function decodeWithPapiFallback(innerData, codec, method) {
+	try {
+		const fullResult = new Uint8Array(1 + innerData.length);
+		fullResult[0] = 0;
+		fullResult.set(innerData, 1);
+		const papiResult = codec.value.dec(fullResult);
+		if (papiResult !== null && typeof papiResult === "object" && "success" in papiResult && "value" in papiResult) {
+			if (papiResult.success) return {
+				success: true,
+				value: papiResult.value
+			};
+			return {
+				success: false,
+				error: new DecodeError(method, `Contract returned error: ${JSON.stringify(papiResult.value)}`, papiResult.value)
+			};
+		}
+		return {
+			success: true,
+			value: papiResult
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: new DecodeError(method, `Failed to decode response: ${error instanceof Error ? error.message : String(error)}`, { error })
+		};
+	}
+}
+/**
 * Patch LangError type in ink metadata to fix the missing index 0 variant issue.
 * Uses structuredClone for efficient deep cloning.
 */
@@ -1225,35 +1270,20 @@ function createD9InkContract(descriptor, address, options) {
 				decodedResponse = decoder.dec(innerData);
 			} catch (decodeError) {
 				console.warn("D9InkContract: Failed to decode response:", decodeError);
-				const fullResult = new Uint8Array(1 + innerData.length);
-				fullResult[0] = 0;
-				fullResult.set(innerData, 1);
-				try {
-					const papiResult = codec.value.dec(fullResult);
-					if (papiResult !== null && typeof papiResult === "object" && "success" in papiResult && "value" in papiResult) if (papiResult.success) decodedResponse = papiResult.value;
-					else return {
-						success: false,
-						error: new DecodeError(method, `Contract returned error: ${JSON.stringify(papiResult.value)}`, papiResult.value)
-					};
-					else decodedResponse = papiResult;
-				} catch (error) {
-					return {
-						success: false,
-						error: new DecodeError(method, `Failed to decode response: ${error instanceof Error ? error.message : String(error)}`, { error })
-					};
-				}
+				const fallbackResult = decodeWithPapiFallback(innerData, codec, method);
+				if (!fallbackResult.success) return {
+					success: false,
+					error: fallbackResult.error
+				};
+				decodedResponse = fallbackResult.value;
 			}
 			else {
-				const fullResult = new Uint8Array(1 + innerData.length);
-				fullResult[0] = 0;
-				fullResult.set(innerData, 1);
-				const papiResult = codec.value.dec(fullResult);
-				if (papiResult !== null && typeof papiResult === "object" && "success" in papiResult && "value" in papiResult) if (papiResult.success) decodedResponse = papiResult.value;
-				else return {
+				const fallbackResult = decodeWithPapiFallback(innerData, codec, method);
+				if (!fallbackResult.success) return {
 					success: false,
-					error: new DecodeError(method, `Contract returned error: ${JSON.stringify(papiResult.value)}`, papiResult.value)
+					error: fallbackResult.error
 				};
-				else decodedResponse = papiResult;
+				decodedResponse = fallbackResult.value;
 			}
 			return {
 				success: true,
@@ -1346,22 +1376,31 @@ function createD9InkContract(descriptor, address, options) {
 		return createSendableTransaction(method, sendOptions);
 	}
 	/**
-	* Create storage query interface
+	* Create storage query interface.
+	*
+	* @deprecated Storage queries are not yet implemented. This API is exposed for
+	* future compatibility but will throw errors if used. Use contract messages
+	* (query/send) to read contract state instead.
+	*
+	* @returns ContractStorage interface with unimplemented methods
 	*/
 	function getStorage() {
+		const notImplementedWarning = (method) => {
+			console.warn(`[D9InkContract] ${method}() is not implemented. Storage queries are planned for a future release. Use contract messages to read state instead.`);
+		};
 		return {
 			async getRoot() {
-				console.warn("D9InkContract: getRoot not implemented");
+				notImplementedWarning("getRoot");
 				return {
 					success: false,
-					value: new ContractError("Storage queries not yet implemented", "METADATA_ERROR")
+					value: new ContractError("Storage queries not yet implemented. Use contract messages to read state.", "METADATA_ERROR")
 				};
 			},
 			async getNested(path, ..._keys) {
-				console.warn("D9InkContract: getNested not implemented");
+				notImplementedWarning("getNested");
 				return {
 					success: false,
-					value: new ContractError(`Storage query for "${path}" not yet implemented`, "METADATA_ERROR")
+					value: new ContractError(`Storage query for "${path}" not yet implemented. Use contract messages to read state.`, "METADATA_ERROR")
 				};
 			}
 		};
@@ -2016,7 +2055,6 @@ exports.createPSP22TransferStream = createPSP22TransferStream;
 exports.createTypedRpc = createTypedRpc;
 exports.decodeContractCallResult = decodeContractCallResult;
 exports.decodeInkValue = decodeInkValue;
-exports.decodeResult = decodeResult;
 exports.encodeCall = encodeCall;
 exports.encodeContractCall = encodeContractCall;
 exports.encodeContractCallWithLimits = encodeContractCallWithLimits;