@kynesyslabs/demosdk 2.10.2 → 2.11.0

package/build/types/blockchain/Transaction.d.ts

@@ -17,10 +17,11 @@ import { ContractCallPayload } from "./TransactionSubtypes/ContractCallTransacti
 import { D402PaymentPayload } from "./TransactionSubtypes/D402PaymentTransaction";
 import { EscrowPayload } from "./TransactionSubtypes/EscrowTransaction";
 import { IPFSPayload } from "./TransactionSubtypes/IPFSTransaction";
+import { TokenCreationPayload, TokenExecutionPayload } from "./TransactionSubtypes/TokenTransaction";
 import { CustomCharges } from "./CustomCharges";
-export type TransactionContentData = ["web2Request", IWeb2Payload] | ["crosschainOperation", XMScript] | ["native", INativePayload] | ["demoswork", DemoScript] | ["l2psEncryptedTx", L2PSEncryptedPayload] | ["identity", IdentityPayload] | ["instantMessaging", InstantMessagingPayload] | ["nativeBridge", NativeBridgeTxPayload] | ["storage", StoragePayload] | ["storageProgram", StorageProgramPayload] | ["l2ps_hash_update", L2PSHashPayload] | ["contractDeploy", ContractDeployPayload] | ["contractCall", ContractCallPayload] | ["d402_payment", D402PaymentPayload] | ["escrow", EscrowPayload] | ["ipfs", IPFSPayload];
+export type TransactionContentData = ["web2Request", IWeb2Payload] | ["crosschainOperation", XMScript] | ["native", INativePayload] | ["demoswork", DemoScript] | ["l2psEncryptedTx", L2PSEncryptedPayload] | ["identity", IdentityPayload] | ["instantMessaging", InstantMessagingPayload] | ["nativeBridge", NativeBridgeTxPayload] | ["storage", StoragePayload] | ["storageProgram", StorageProgramPayload] | ["l2ps_hash_update", L2PSHashPayload] | ["contractDeploy", ContractDeployPayload] | ["contractCall", ContractCallPayload] | ["d402_payment", D402PaymentPayload] | ["escrow", EscrowPayload] | ["ipfs", IPFSPayload] | ["tokenCreation", TokenCreationPayload] | ["tokenExecution", TokenExecutionPayload];
 export interface TransactionContent {
-    type: "web2Request" | "crosschainOperation" | "subnet" | "native" | "demoswork" | "genesis" | "NODE_ONLINE" | "identity" | "instantMessaging" | "nativeBridge" | "l2psEncryptedTx" | "storage" | "storageProgram" | "l2ps_hash_update" | "contractDeploy" | "contractCall" | "d402_payment" | "escrow" | "ipfs";
+    type: "web2Request" | "crosschainOperation" | "subnet" | "native" | "demoswork" | "genesis" | "NODE_ONLINE" | "identity" | "instantMessaging" | "nativeBridge" | "l2psEncryptedTx" | "storage" | "storageProgram" | "l2ps_hash_update" | "contractDeploy" | "contractCall" | "d402_payment" | "escrow" | "ipfs" | "tokenCreation" | "tokenExecution";
     from: string;
     from_ed25519_address: string;
     to: string;

package/build/types/blockchain/Transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../../../src/types/blockchain/Transaction.ts"],"names":[],"mappings":"AAqGA,uCAAuC;AACvC,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../../../src/types/blockchain/Transaction.ts"],"names":[],"mappings":"AA0GA,uCAAuC;AACvC,cAAc,uBAAuB,CAAA"}

package/build/types/blockchain/TransactionSubtypes/TokenTransaction.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Token Transaction Types
+ *
+ * Defines transaction subtypes for token operations:
+ * - tokenCreation: Deploy new tokens
+ * - tokenExecution: Execute token methods (transfer, mint, burn, etc.)
+ */
+import { Transaction, TransactionContent } from "../Transaction";
+import type { TokenHookType, TokenScriptMethod } from "../../token";
+/**
+ * Payload for creating a new token.
+ */
+export interface TokenCreationPayload {
+    /** Token name (1-50 alphanumeric chars with spaces) */
+    name: string;
+    /** Token ticker (1-10 uppercase alphanumeric chars) */
+    ticker: string;
+    /** Decimal places (0-18) */
+    decimals: number;
+    /** Initial supply as string (bigint serialization) */
+    initialSupply: string;
+    /** Optional script for advanced tokens */
+    script?: {
+        code: string;
+        methods: TokenScriptMethod[];
+        hooks: TokenHookType[];
+    };
+    /** Initial ACL entries (owner is always included) */
+    initialACL?: Array<{
+        address: string;
+        permissions: string[];
+    }>;
+}
+export type TokenCreationTransactionContent = Omit<TransactionContent, "type" | "data"> & {
+    type: "tokenCreation";
+    data: ["tokenCreation", TokenCreationPayload];
+};
+export interface TokenCreationTransaction extends Omit<Transaction, "content"> {
+    content: TokenCreationTransactionContent;
+}
+/**
+ * Standard token operation types.
+ */
+export type TokenOperationType = "transfer" | "approve" | "transferFrom" | "mint" | "burn" | "pause" | "unpause" | "transferOwnership" | "modifyACL" | "upgradeScript" | "custom";
+/**
+ * Payload for executing token operations.
+ */
+export interface TokenExecutionPayload {
+    /** Token address (derived from deployer + nonce + hash) */
+    tokenAddress: string;
+    /** Operation type */
+    operation: TokenOperationType;
+    /** Operation arguments - structure depends on operation type */
+    args: TokenOperationArgs;
+}
+/**
+ * Union of all possible operation argument structures.
+ */
+export type TokenOperationArgs = TokenTransferArgs | TokenApproveArgs | TokenTransferFromArgs | TokenMintArgs | TokenBurnArgs | TokenPauseArgs | TokenOwnershipArgs | TokenACLArgs | TokenUpgradeArgs | TokenCustomArgs;
+/**
+ * Arguments for transfer operation.
+ */
+export interface TokenTransferArgs {
+    type: "transfer";
+    to: string;
+    amount: string;
+}
+/**
+ * Arguments for approve operation.
+ */
+export interface TokenApproveArgs {
+    type: "approve";
+    spender: string;
+    amount: string;
+}
+/**
+ * Arguments for transferFrom operation.
+ */
+export interface TokenTransferFromArgs {
+    type: "transferFrom";
+    from: string;
+    to: string;
+    amount: string;
+}
+/**
+ * Arguments for mint operation.
+ */
+export interface TokenMintArgs {
+    type: "mint";
+    to: string;
+    amount: string;
+}
+/**
+ * Arguments for burn operation.
+ */
+export interface TokenBurnArgs {
+    type: "burn";
+    from: string;
+    amount: string;
+}
+/**
+ * Arguments for pause/unpause operations.
+ */
+export interface TokenPauseArgs {
+    type: "pause" | "unpause";
+}
+/**
+ * Arguments for ownership transfer.
+ */
+export interface TokenOwnershipArgs {
+    type: "transferOwnership";
+    newOwner: string;
+}
+/**
+ * Arguments for ACL modification.
+ */
+export interface TokenACLArgs {
+    type: "modifyACL";
+    action: "grant" | "revoke";
+    address: string;
+    permissions: string[];
+}
+/**
+ * Arguments for script upgrade.
+ */
+export interface TokenUpgradeArgs {
+    type: "upgradeScript";
+    newCode: string;
+    newMethods: TokenScriptMethod[];
+    newHooks: TokenHookType[];
+}
+/**
+ * Arguments for custom script methods.
+ */
+export interface TokenCustomArgs {
+    type: "custom";
+    method: string;
+    params: unknown[];
+}
+export type TokenExecutionTransactionContent = Omit<TransactionContent, "type" | "data"> & {
+    type: "tokenExecution";
+    data: ["tokenExecution", TokenExecutionPayload];
+};
+export interface TokenExecutionTransaction extends Omit<Transaction, "content"> {
+    content: TokenExecutionTransactionContent;
+}
+/**
+ * Type guard for TokenCreationPayload.
+ */
+export declare function isTokenCreationPayload(payload: unknown): payload is TokenCreationPayload;
+/**
+ * Type guard for TokenExecutionPayload.
+ */
+export declare function isTokenExecutionPayload(payload: unknown): payload is TokenExecutionPayload;
+/**
+ * Type guard for TokenCreationTransaction.
+ */
+export declare function isTokenCreationTransaction(tx: Transaction): tx is TokenCreationTransaction;
+/**
+ * Type guard for TokenExecutionTransaction.
+ */
+export declare function isTokenExecutionTransaction(tx: Transaction): tx is TokenExecutionTransaction;

package/build/types/blockchain/TransactionSubtypes/TokenTransaction.js

@@ -0,0 +1,48 @@
+/**
+ * Token Transaction Types
+ *
+ * Defines transaction subtypes for token operations:
+ * - tokenCreation: Deploy new tokens
+ * - tokenExecution: Execute token methods (transfer, mint, burn, etc.)
+ */
+// SECTION: Type Guards
+/**
+ * Type guard for TokenCreationPayload.
+ */
+export function isTokenCreationPayload(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return false;
+    const p = payload;
+    return (typeof p.name === "string" &&
+        typeof p.ticker === "string" &&
+        typeof p.decimals === "number" &&
+        typeof p.initialSupply === "string");
+}
+/**
+ * Type guard for TokenExecutionPayload.
+ */
+export function isTokenExecutionPayload(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return false;
+    const p = payload;
+    return (typeof p.tokenAddress === "string" &&
+        typeof p.operation === "string" &&
+        typeof p.args === "object");
+}
+/**
+ * Type guard for TokenCreationTransaction.
+ */
+export function isTokenCreationTransaction(tx) {
+    return (tx.content.type === "tokenCreation" &&
+        Array.isArray(tx.content.data) &&
+        tx.content.data[0] === "tokenCreation");
+}
+/**
+ * Type guard for TokenExecutionTransaction.
+ */
+export function isTokenExecutionTransaction(tx) {
+    return (tx.content.type === "tokenExecution" &&
+        Array.isArray(tx.content.data) &&
+        tx.content.data[0] === "tokenExecution");
+}
+//# sourceMappingURL=TokenTransaction.js.map

package/build/types/blockchain/TransactionSubtypes/TokenTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenTransaction.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/TokenTransaction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6LH,uBAAuB;AAEvB;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACnD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IACjE,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,OAAO,CACH,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ,CACtC,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACpD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IACjE,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,OAAO,CACH,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ;QAClC,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAC7B,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,EAAe;IACtD,OAAO,CACH,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,eAAe;QACnC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;QAC9B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,eAAe,CACzC,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAAe;IACvD,OAAO,CACH,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,gBAAgB;QACpC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;QAC9B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAC1C,CAAA;AACL,CAAC"}

package/build/types/blockchain/TransactionSubtypes/index.d.ts

@@ -14,6 +14,7 @@ export * from './ContractCallTransaction';
 export * from './D402PaymentTransaction';
 export * from './EscrowTransaction';
 export * from './IPFSTransaction';
+export * from './TokenTransaction';
 import { L2PSTransaction } from './L2PSTransaction';
 import { L2PSHashTransaction } from './L2PSHashTransaction';
 import { Web2Transaction } from './Web2Transaction';
@@ -30,4 +31,6 @@ import { ContractCallTransaction } from './ContractCallTransaction';
 import { D402PaymentTransaction } from './D402PaymentTransaction';
 import { EscrowTransaction } from './EscrowTransaction';
 import { IPFSTransaction } from './IPFSTransaction';
-export type SpecificTransaction = L2PSTransaction | L2PSHashTransaction | Web2Transaction | CrosschainTransaction | NativeTransaction | DemosworkTransaction | IdentityTransaction | InstantMessagingTransaction | NativeBridgeTransaction | StorageTransaction | StorageProgramTransaction | ContractDeployTransaction | ContractCallTransaction | D402PaymentTransaction | EscrowTransaction | IPFSTransaction;
+import { TokenCreationTransaction } from './TokenTransaction';
+import { TokenExecutionTransaction } from './TokenTransaction';
+export type SpecificTransaction = L2PSTransaction | L2PSHashTransaction | Web2Transaction | CrosschainTransaction | NativeTransaction | DemosworkTransaction | IdentityTransaction | InstantMessagingTransaction | NativeBridgeTransaction | StorageTransaction | StorageProgramTransaction | ContractDeployTransaction | ContractCallTransaction | D402PaymentTransaction | EscrowTransaction | IPFSTransaction | TokenCreationTransaction | TokenExecutionTransaction;

package/build/types/blockchain/TransactionSubtypes/index.js

@@ -14,4 +14,6 @@ export * from './ContractCallTransaction.js';
 export * from './D402PaymentTransaction.js';
 export * from './EscrowTransaction.js';
 export * from './IPFSTransaction.js';
+// REVIEW: Token transaction types
+export * from './TokenTransaction.js';
 //# sourceMappingURL=index.js.map

package/build/types/blockchain/TransactionSubtypes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,kCAAkC;AAClC,cAAc,oBAAoB,CAAA"}

package/build/types/index.d.ts

@@ -37,3 +37,4 @@ export { type SigningAlgorithm, type EncryptionAlgorithm } from "./cryptography"
 export { Ed25519SignedObject, PqcSignedObject, encryptedObject, SerializedEncryptedObject, SerializedSignedObject, signedObject, } from "../encryption/unifiedCrypto";
 export { isTransactionType, isTransactionDataType, } from "./blockchain/TransactionSubtypes/utils";
 export { type SignatureType, type UDNetwork, type UDRegistryType, type UDRecordKey, type SolanaRecordResult, type SolanaDomainResolution, type EVMDomainResolution, type SignableAddress, type UnifiedDomainResolution, type UDIdentityAssignPayload, type UDIdentityPayload, type UDResolutionConfig, type AddressTypeInfo, } from "../abstraction/types/UDResolution";
+export { type TokenPermission, type TokenACLEntry, type TokenAccessControl, type TokenMetadata, type TokenBalances, type TokenAllowances, type TokenCustomState, type TokenState, type TokenHookType, type TokenScriptMethod, type TokenScript, type TokenData, type TokenHolderReference, type StateMutation, type ScriptContext, type ScriptExecutionResult, type TokenCreationParams, type TokenQueryResult, type TokenBalanceResult, deriveTokenAddress, computeScriptHash, serializeTokenData, deserializeTokenData, balanceToString, stringToBalance, createInitialTokenState, createInitialAccessControl, createTokenMetadata, createHolderReference, isValidTicker, isValidTokenName, isValidDecimals, isValidBalance, validateTokenCreationParams, applyMutations, hasPermission, } from "./token";

package/build/types/index.js

@@ -13,4 +13,8 @@ export { emptyResponse as RPCResponseSkeleton, } from "./communication/rpc.js";
 export { ChainProviders, SupportedChains, SupportedTokens, } from "./bridge/constants.js";
 // Export transaction utilities
 export { isTransactionType, isTransactionDataType, } from "./blockchain/TransactionSubtypes/utils.js";
+// REVIEW: Token types for Demos Network tokens with scripting support
+export { 
+// Utility functions
+deriveTokenAddress, computeScriptHash, serializeTokenData, deserializeTokenData, balanceToString, stringToBalance, createInitialTokenState, createInitialAccessControl, createTokenMetadata, createHolderReference, isValidTicker, isValidTokenName, isValidDecimals, isValidBalance, validateTokenCreationParams, applyMutations, hasPermission, } from "./token";
 //# sourceMappingURL=index.js.map

package/build/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAmBA,gEAAgE;AAChE,OAAO,EAKH,oBAAoB,EACpB,aAAa,GAChB,MAAM,4BAA4B,CAAA;AAEnC,wCAAwC;AACxC,OAAO,EAoBH,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB;AAClB,6CAA6C;AAC7C,sBAAsB,EACtB,aAAa,GAChB,MAAM,kCAAkC,CAAA;AASzC,OAAO,EAAE,aAAa,EAAgB,MAAM,2BAA2B,CAAA;AA6CvE,OAAO;AACP,OAAO,EAaH,eAAe,GAClB,MAAM,QAAQ,CAAA;AAef,OAAO,EAAE,SAAS,EAAa,MAAM,uBAAuB,CAAA;AAO5D,OAAO,EAKH,YAAY,EAEZ,YAAY,GACf,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EASH,aAAa,IAAI,mBAAmB,GACvC,MAAM,qBAAqB,CAAA;AAgB5B,OAAO,EACH,cAAc,EACd,eAAe,EACf,eAAe,GAClB,MAAM,oBAAoB,CAAA;AAY3B,+BAA+B;AAC/B,OAAO,EACH,iBAAiB,EACjB,qBAAqB,GACxB,MAAM,wCAAwC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAmBA,gEAAgE;AAChE,OAAO,EAKH,oBAAoB,EACpB,aAAa,GAChB,MAAM,4BAA4B,CAAA;AAEnC,wCAAwC;AACxC,OAAO,EAoBH,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB;AAClB,6CAA6C;AAC7C,sBAAsB,EACtB,aAAa,GAChB,MAAM,kCAAkC,CAAA;AASzC,OAAO,EAAE,aAAa,EAAgB,MAAM,2BAA2B,CAAA;AA6CvE,OAAO;AACP,OAAO,EAaH,eAAe,GAClB,MAAM,QAAQ,CAAA;AAef,OAAO,EAAE,SAAS,EAAa,MAAM,uBAAuB,CAAA;AAO5D,OAAO,EAKH,YAAY,EAEZ,YAAY,GACf,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EASH,aAAa,IAAI,mBAAmB,GACvC,MAAM,qBAAqB,CAAA;AAgB5B,OAAO,EACH,cAAc,EACd,eAAe,EACf,eAAe,GAClB,MAAM,oBAAoB,CAAA;AAY3B,+BAA+B;AAC/B,OAAO,EACH,iBAAiB,EACjB,qBAAqB,GACxB,MAAM,wCAAwC,CAAA;AAmB/C,sEAAsE;AACtE,OAAO;AA4BH,oBAAoB;AACpB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,2BAA2B,EAC3B,cAAc,EACd,aAAa,GAChB,MAAM,SAAS,CAAA"}

package/build/types/token/TokenTypes.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Token Types for Demos Network
+ *
+ * Defines the core data structures for fungible tokens with scripting support.
+ * Tokens are stored as GCR accounts with special properties in the data field.
+ *
+ * Storage Model:
+ * - Token data stored in token's GCR `details.content.token`
+ * - Holder pointers stored in holder's `GCRExtended.tokens` array
+ */
+/**
+ * Permission flags for token access control.
+ * Each permission can be granted to addresses in the ACL.
+ */
+export type TokenPermission = "canMint" | "canBurn" | "canUpgrade" | "canPause" | "canTransferOwnership" | "canModifyACL" | "canExecuteScript";
+/**
+ * Access Control List entry for a single address.
+ */
+export interface TokenACLEntry {
+    address: string;
+    permissions: TokenPermission[];
+    grantedAt: number;
+    grantedBy: string;
+}
+/**
+ * Token Access Control structure.
+ * Owner has all permissions by default.
+ */
+export interface TokenAccessControl {
+    owner: string;
+    paused: boolean;
+    entries: TokenACLEntry[];
+}
+/**
+ * Immutable token metadata set at creation time.
+ */
+export interface TokenMetadata {
+    name: string;
+    ticker: string;
+    decimals: number;
+    address: string;
+    deployer: string;
+    deployerNonce: number;
+    deployedAt: number;
+    hasScript: boolean;
+}
+/**
+ * Token balances mapping: address -> balance
+ * Stored centrally in the token's GCR
+ */
+export type TokenBalances = Record<string, string>;
+/**
+ * Token allowances mapping: owner -> spender -> amount
+ * For ERC20-like approve/transferFrom pattern
+ */
+export type TokenAllowances = Record<string, Record<string, string>>;
+/**
+ * Custom state for scripted tokens.
+ * Scripts can store arbitrary data here.
+ */
+export type TokenCustomState = Record<string, unknown>;
+/**
+ * Complete token state.
+ */
+export interface TokenState {
+    totalSupply: string;
+    balances: TokenBalances;
+    allowances: TokenAllowances;
+    customState: TokenCustomState;
+}
+/**
+ * Hook types that can trigger script execution.
+ * Hooks EXTEND native operations, they don't override them.
+ */
+export type TokenHookType = "beforeTransfer" | "afterTransfer" | "beforeMint" | "afterMint" | "beforeBurn" | "afterBurn" | "onApprove";
+/**
+ * Script method definition for custom token logic.
+ */
+export interface TokenScriptMethod {
+    name: string;
+    params: Array<{
+        name: string;
+        type: string;
+    }>;
+    returns?: string;
+    mutates: boolean;
+}
+/**
+ * Token script definition.
+ * Contains the script code and method signatures.
+ */
+export interface TokenScript {
+    version: number;
+    code: string;
+    methods: TokenScriptMethod[];
+    hooks: TokenHookType[];
+    codeHash: string;
+    upgradedAt: number;
+}
+/**
+ * Complete token data as stored in GCR.
+ * This is the full structure stored in `details.content.token`
+ */
+export interface TokenData {
+    metadata: TokenMetadata;
+    state: TokenState;
+    accessControl: TokenAccessControl;
+    script?: TokenScript;
+}
+/**
+ * Lightweight token reference stored in holder's GCRExtended.tokens
+ * Points to the token GCR for full data lookup
+ */
+export interface TokenHolderReference {
+    tokenAddress: string;
+    ticker: string;
+    name: string;
+    decimals: number;
+}
+/**
+ * State mutation returned by scripts.
+ * Scripts return a list of mutations, not the new state directly.
+ */
+export interface StateMutation {
+    type: "setBalance" | "addBalance" | "subBalance" | "setCustomState" | "setAllowance";
+    address?: string;
+    spender?: string;
+    value: string | number | Record<string, unknown>;
+    key?: string;
+}
+/**
+ * Context provided to script execution.
+ * Contains deterministic values only.
+ */
+export interface ScriptContext {
+    caller: string;
+    method: string;
+    args: unknown[];
+    tokenState: Readonly<TokenState>;
+    tokenMetadata: Readonly<TokenMetadata>;
+    txTimestamp: number;
+    prevBlockHash: string;
+    blockHeight: number;
+}
+/**
+ * Result of script execution.
+ */
+export interface ScriptExecutionResult {
+    success: boolean;
+    mutations: StateMutation[];
+    returnValue?: unknown;
+    error?: string;
+    complexity: number;
+}
+/**
+ * Token creation parameters.
+ */
+export interface TokenCreationParams {
+    name: string;
+    ticker: string;
+    decimals: number;
+    initialSupply: string;
+    script?: {
+        code: string;
+        methods: TokenScriptMethod[];
+        hooks: TokenHookType[];
+    };
+    initialACL?: Omit<TokenACLEntry, "grantedAt" | "grantedBy">[];
+}
+/**
+ * Token query result for nodeCall responses.
+ */
+export interface TokenQueryResult {
+    exists: boolean;
+    metadata?: TokenMetadata;
+    state?: TokenState;
+    accessControl?: TokenAccessControl;
+    hasScript?: boolean;
+}
+/**
+ * Token balance query result.
+ */
+export interface TokenBalanceResult {
+    tokenAddress: string;
+    holderAddress: string;
+    balance: string;
+    decimals: number;
+    ticker: string;
+}

package/build/types/token/TokenTypes.js

@@ -0,0 +1,12 @@
+/**
+ * Token Types for Demos Network
+ *
+ * Defines the core data structures for fungible tokens with scripting support.
+ * Tokens are stored as GCR accounts with special properties in the data field.
+ *
+ * Storage Model:
+ * - Token data stored in token's GCR `details.content.token`
+ * - Holder pointers stored in holder's `GCRExtended.tokens` array
+ */
+export {};
+//# sourceMappingURL=TokenTypes.js.map

package/build/types/token/TokenTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenTypes.js","sourceRoot":"","sources":["../../../../src/types/token/TokenTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/build/types/token/TokenUtils.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Token Utility Functions
+ *
+ * Provides address derivation, serialization, and validation utilities.
+ */
+import type { TokenData, TokenMetadata, TokenState, TokenAccessControl, TokenCreationParams, TokenHolderReference, StateMutation } from "./TokenTypes";
+/**
+ * Derives a deterministic token address from deployer info and token params.
+ * Formula: sha256(deployer + nonce + hash(tokenObject))
+ *
+ * @param deployer - Deployer's address
+ * @param nonce - Deployer's nonce at deployment time
+ * @param tokenParams - Token creation parameters
+ * @returns Deterministic token address (0x-prefixed)
+ */
+export declare function deriveTokenAddress(deployer: string, nonce: number, tokenParams: TokenCreationParams): string;
+/**
+ * Computes the hash of script code for verification.
+ *
+ * @param code - Script source code
+ * @returns SHA256 hash of the code
+ */
+export declare function computeScriptHash(code: string): string;
+/**
+ * Serializes TokenData for GCR storage.
+ * Ensures consistent serialization for consensus.
+ */
+export declare function serializeTokenData(data: TokenData): string;
+/**
+ * Deserializes TokenData from GCR storage.
+ */
+export declare function deserializeTokenData(serialized: string): TokenData;
+/**
+ * Converts a bigint balance to string for storage.
+ */
+export declare function balanceToString(balance: bigint): string;
+/**
+ * Converts a string balance back to bigint for calculations.
+ */
+export declare function stringToBalance(str: string): bigint;
+/**
+ * Creates initial token state from creation parameters.
+ */
+export declare function createInitialTokenState(params: TokenCreationParams, deployerAddress: string): TokenState;
+/**
+ * Creates initial access control with deployer as owner.
+ */
+export declare function createInitialAccessControl(ownerAddress: string, timestamp: number, initialACL?: TokenCreationParams["initialACL"]): TokenAccessControl;
+/**
+ * Creates complete TokenMetadata from creation parameters.
+ */
+export declare function createTokenMetadata(params: TokenCreationParams, deployerAddress: string, deployerNonce: number, timestamp: number): TokenMetadata;
+/**
+ * Creates a holder reference for storage in GCRExtended.tokens
+ */
+export declare function createHolderReference(metadata: TokenMetadata): TokenHolderReference;
+/**
+ * Validates token ticker format.
+ * Must be 1-10 uppercase alphanumeric characters.
+ */
+export declare function isValidTicker(ticker: string): boolean;
+/**
+ * Validates token name.
+ * Must be 1-50 characters, alphanumeric with spaces.
+ */
+export declare function isValidTokenName(name: string): boolean;
+/**
+ * Validates decimals range.
+ * Must be 0-18 (like most blockchain tokens).
+ */
+export declare function isValidDecimals(decimals: number): boolean;
+/**
+ * Validates a balance string is a valid non-negative integer.
+ */
+export declare function isValidBalance(balance: string): boolean;
+/**
+ * Validates token creation parameters.
+ */
+export declare function validateTokenCreationParams(params: TokenCreationParams): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Applies a list of state mutations to token state.
+ * Used after script execution to update state.
+ *
+ * @param state - Current token state
+ * @param mutations - List of mutations to apply
+ * @returns New token state with mutations applied
+ */
+export declare function applyMutations(state: TokenState, mutations: StateMutation[]): TokenState;
+/**
+ * Checks if an address has a specific permission.
+ */
+export declare function hasPermission(accessControl: TokenAccessControl, address: string, permission: string): boolean;