@terminal3/t3n-sdk 3.5.2 → 3.6.0

package/dist/index.d.ts

@@ -865,9 +865,15 @@ interface OrgDataActionWire {
  * `available` and `reserved` are `u128` on the server; the wire
  * format is a JSON number. Callers should not assume bigint until
  * the SDK migrates to a streaming parser (tracked separately).
+ *
+ * ⚠️ Amounts are in **base units** (`1 token = `
+ * {@link BASE_UNITS_PER_TOKEN}), not whole tokens. Use
+ * {@link formatTokens} to display them.
  */
 interface BalanceRow {
+    /** Spendable balance, in base units (see {@link formatTokens}). */
     available: number;
+    /** Reserved balance, in base units. */
     reserved: number;
     last_settled_seq_no: number;
     version: number;
@@ -922,6 +928,7 @@ type ChargeReason = {
 interface UsageEntry {
     seq_no: number;
     kind: TokenTxKind;
+    /** Amount moved, in base units (`1 token = `{@link BASE_UNITS_PER_TOKEN}); see {@link formatTokens}. */
     amount: number;
     timestamp_ms: number;
     direction: Direction;
@@ -2733,6 +2740,45 @@ declare class SessionOrgDataClient {
  */
 declare function createOrgDataClientFromSession(t3n: T3nClient, baseUrl: string): SessionOrgDataClient;
 
+/**
+ * Token fixed-point units (USDT-style 6 decimals).
+ *
+ * As of `tee:*` metering v2, every token amount on the wire —
+ * {@link BalanceRow}'s `available`/`reserved`, {@link UsageEntry.amount},
+ * and `total_supply` — is denominated in **base units**, where
+ * `1 T3N token = `{@link BASE_UNITS_PER_TOKEN}` base units`. The node
+ * meters the *actual* fractional cost of each operation (pro-rata by
+ * bytes / byte-seconds / fuel) down to `1e-6` token, so amounts are
+ * raw integers in base units, NOT whole tokens.
+ *
+ * The wire fields are left as raw base units (no silent rescaling — that
+ * would lose precision for large balances and surprise callers doing
+ * arithmetic). Use {@link formatTokens} to render a human "tokens"
+ * string and {@link toBaseUnits} to convert a token figure back.
+ *
+ * ⚠️ Breaking vs. the pre-decimals SDK: a balance that used to read `5`
+ * (whole tokens) now reads `5_000_000` (base units). Multiply existing
+ * display code through {@link formatTokens}.
+ */
+/** Decimal places in a T3N token (fixed; mirrors the node constant). */
+declare const TOKEN_DECIMALS = 6;
+/** Base units per whole T3N token — `10 ** TOKEN_DECIMALS`. */
+declare const BASE_UNITS_PER_TOKEN = 1000000;
+/**
+ * Render a base-unit amount as a human-readable token string, e.g.
+ * `25_920_000 → "25.92"`, `1_000_000 → "1"`, `4768 → "0.004768"`.
+ *
+ * Trailing-zero fraction digits are trimmed; an integer amount renders
+ * with no decimal point. Accepts `number` or `bigint`; for balances
+ * above `Number.MAX_SAFE_INTEGER` prefer passing a `bigint`.
+ */
+declare function formatTokens(baseUnits: number | bigint): string;
+/**
+ * Convert a whole-or-fractional token figure to base units (rounded to
+ * the nearest base unit). E.g. `25.92 → 25_920_000`, `1 → 1_000_000`.
+ */
+declare function toBaseUnits(tokens: number): number;
+
 /**
  * Cryptographic utilities for T3n SDK
  *
@@ -3185,5 +3231,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicalTenantName, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, tenantDidHex, validateConfig, validateCredentialBody, validateTail, verifyDkgAttestation, verifyTdxQuote };
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicalTenantName, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, tenantDidHex, toBaseUnits, validateConfig, validateCredentialBody, validateTail, verifyDkgAttestation, verifyTdxQuote };
 export type { AgeBand, AuthInput, BalanceRow, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractPublishInput, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, ExpenseClaim, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, ResidencyCategory, RevokeDelegationOpts, RevokeDelegationResult, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WriterSet, WritersGetInput };