@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/dist/src/types.d.ts

@@ -0,0 +1,448 @@
+import type { AccountRef } from './crypto/account-id';
+import type { GeeqHeldNft } from './ledger/coin-accounts';
+import type { GeeqProxyAccount } from './ledger/proxy-accounts';
+/**
+ * Where the WebAssembly engine should be loaded from. Leave it unset and the SDK
+ * uses the copy shipped beside its own bundle, which every common bundler emits
+ * as a hashed asset automatically.
+ */
+export type WasmSource = string | URL | Request | Response | ArrayBuffer | Uint8Array | WebAssembly.Module;
+export interface InitOptions {
+    /** Override where `geeq_core_bg.wasm` is fetched from. */
+    readonly wasm?: WasmSource;
+}
+/**
+ * The kind of ledger record an address points at. Most applications only ever
+ * need `'coin-asset'`, which is the default and is what a normal user account is.
+ */
+export type GeeqRecordType = 'coin-asset' | 'coin-hl' | 'coin-micro' | 'app-counterparty' | 'app-dce' | 'app-nft' | 'app-stackable' | 'proxy-nft-mint' | 'proxy-funding' | 'proxy-multisig' | 'proxy-dce' | 'proxy-token-mint' | 'gt-nwa' | 'param-boolean' | 'param-count-2' | 'param-count-8' | 'sys';
+/** Which coin family a derivation path belongs to. */
+export type GeeqCoinType = 'mainnet' | 'testnet';
+export interface WalletAddressOptions {
+    /** The chain this address belongs to. Addresses are not portable across chains. */
+    readonly chainNumber: number;
+    /** Defaults to `'coin-asset'` — an ordinary user account. */
+    readonly recordType?: GeeqRecordType;
+}
+export interface DecodedWalletAddress {
+    /** The address that was decoded, unchanged. */
+    readonly address: string;
+    readonly chainNumber: number;
+    readonly recordType: GeeqRecordType;
+    /** The 32-byte account id this address points at. */
+    readonly accountId: Uint8Array;
+}
+/** Options for deriving a keypair from a BIP-39 mnemonic along the Geeq path. */
+export interface MnemonicOptions {
+    /** Optional BIP-39 passphrase. Defaults to an empty string. */
+    readonly passphrase?: string;
+    /** Defaults to `'coin-asset'`. */
+    readonly recordType?: GeeqRecordType;
+    /** Defaults to `'mainnet'`. */
+    readonly coinType?: GeeqCoinType;
+    /** Defaults to 0. */
+    readonly account?: number;
+    /** Defaults to 0. */
+    readonly addressIndex?: number;
+}
+/**
+ * An Ed25519 keypair plus the identifiers derived from it.
+ *
+ * `privateKey` is raw secret material. Never log it, never put it in an error
+ * message, and never send it anywhere. Call {@link GeeqKeypair.dispose} when done
+ * to release the engine-side copy.
+ */
+export interface GeeqKeypair {
+    /** 32-byte Ed25519 public key. */
+    readonly publicKey: Uint8Array;
+    /** 32-byte Ed25519 secret key. Secret material. */
+    readonly privateKey: Uint8Array;
+    /** 32-byte account id derived from the public key. */
+    readonly accountId: Uint8Array;
+    /** The base58 wallet address for this keypair on a given chain. */
+    getAddress(options: WalletAddressOptions): string;
+    /** Sign a message. Throws once {@link GeeqKeypair.dispose} has been called. */
+    sign(message: Uint8Array): Uint8Array;
+    /** Release the engine-side keypair. The byte fields stay readable afterwards. */
+    dispose(): void;
+}
+/** The metadata limits this chain publishes in its own ledger. */
+export interface GeeqMetadataLimits {
+    /** Maximum NUMBER of metadata entries. From the `metadataVarNum` parameter. */
+    readonly maxEntries: number;
+    /** Maximum bytes in ONE entry. There is no aggregate cap. From `metadataVarBytes`. */
+    readonly maxBytesPerEntry: number;
+}
+/**
+ * The live chain values a transaction is pinned to.
+ *
+ * `blockNumber` is the block being *asked for*, which is the ledger's last committed
+ * block plus one. Read it from a node with {@link GeeqChain}, or supply it yourself for
+ * replay and offline signing.
+ */
+export interface ChainStateInput {
+    /** The chain this transaction targets — the ledger's own chain number. */
+    readonly chainNumber: number;
+    /** The block it asks to be included in: the ledger's block **+ 1**. */
+    readonly blockNumber: number;
+    /** The receiving node's own number, from the net actor list in the ledger. */
+    readonly nodeNumber: number;
+    /** The signing account's current nonce, from its coin account record. */
+    readonly nonce: number;
+    /** When present, metadata is checked against it before anything is signed. */
+    readonly metadataLimits?: GeeqMetadataLimits | undefined;
+    /**
+     * The chain's `geeqNorm` parameter, which every fee is a multiple of. When present, the
+     * built transaction carries its {@link GeeqFee}.
+     */
+    readonly geeqNorm?: bigint | undefined;
+    /**
+     * The node this state describes, and therefore the only node that will accept a
+     * transaction built from it — `nodeNumber` is checked with strict equality.
+     */
+    readonly nodeUrl?: string | undefined;
+    /**
+     * N, the ledger block this was read from. Present only when a chain produced it —
+     * there is nothing to report when the caller supplied the numbers.
+     */
+    readonly ledgerBlockNumber?: number | undefined;
+    /** `Date.now()` at the read. Present only when a chain produced it. */
+    readonly readAt?: number | undefined;
+}
+/**
+ * Chain state read from a node, carrying where and when it came from.
+ *
+ * The same fields as {@link ChainStateInput}, with the provenance ones narrowed from
+ * optional to always present — a chain can always say which ledger block and which node
+ * it read.
+ */
+export interface GeeqChainState extends ChainStateInput {
+    /** N — the ledger's last committed block. {@link blockNumber} is this plus one. */
+    readonly ledgerBlockNumber: number;
+    /** `Date.now()` when the ledger was read, so callers can see how stale this is. */
+    readonly readAt: number;
+    /** The node it was read from, and therefore the node it must be submitted to. */
+    readonly nodeUrl: string;
+    /** The signing account's balance, in pennies, as at this read. */
+    readonly balance: bigint;
+    /** The smallest transfer this chain accepts, in pennies, if it publishes one. */
+    readonly minimumTransfer: bigint | undefined;
+    /** The chain's `geeqNorm` parameter, if it publishes one. */
+    readonly geeqNorm: bigint | undefined;
+}
+/**
+ * What the chain charges for a transaction, in pennies, on top of any amount it sends.
+ *
+ * Worked out by the SDK the way the node works it out, from the signed bytes, so it is
+ * the exact figure rather than an estimate.
+ */
+export interface GeeqFee {
+    /** The whole fee: {@link data} plus {@link coin}. */
+    readonly total: bigint;
+    /** `geeqNorm` per byte of the signed transaction, and of its payload when it has one. */
+    readonly data: bigint;
+    /**
+     * A quarter of a percent of the amount sent, rounded down and capped at
+     * `geeqNorm × 10⁷`. Zero for an attestation, which sends no amount.
+     */
+    readonly coin: bigint;
+    /** How many bytes {@link data} charges for. */
+    readonly bytes: number;
+}
+/** What is being attested, independent of any chain state. */
+export interface AttestationContent {
+    /** The account that signs both the attestation and the transaction. */
+    readonly keypair: GeeqKeypair;
+    /** 32-byte hash of the content. The content itself never leaves the device. */
+    readonly attestHash: Uint8Array;
+    /**
+     * Optional labels stored alongside the hash, in the order given. Strings are encoded
+     * as UTF-8. Anything here is public once submitted.
+     */
+    readonly metadata?: readonly (string | Uint8Array)[];
+}
+/**
+ * The four chain values supplied explicitly.
+ *
+ * Kept for replay, deterministic tests and air-gapped signing, where there is no node
+ * to ask. Most callers should let {@link GeeqChain} read them instead — none of them can
+ * be derived offline, and a wrong one is rejected by the chain.
+ */
+export type AttestationTxFlatInput = AttestationContent & {
+    readonly chainNumber: number;
+    readonly blockNumber: number;
+    readonly nodeNumber: number;
+    readonly nonce: number;
+    readonly chainState?: never;
+};
+/** The same four values as one object, which is what a chain read produces. */
+export type AttestationTxStateInput = AttestationContent & {
+    readonly chainState: ChainStateInput;
+    readonly chainNumber?: never;
+    readonly blockNumber?: never;
+    readonly nodeNumber?: never;
+    readonly nonce?: never;
+};
+export type AttestationTxInput = AttestationTxFlatInput | AttestationTxStateInput;
+/**
+ * A signed attestation transaction, ready to submit. The SDK does not submit it — post
+ * {@link AttestationTx.transaction} and {@link AttestationTx.payload} to the node named
+ * by {@link AttestationTx.nodeUrl}, after handing it to `GeeqSocket.track` to hear the
+ * verdict.
+ */
+export interface AttestationTx {
+    /** base64 packed `UserAppTx`. Submit as the `transaction` field. */
+    readonly transaction: string;
+    /** base64 packed `Payload`. Submit as the `payload` field. */
+    readonly payload: string;
+    /** 32-byte BLAKE3 of the flattened payload, as embedded in the transaction. */
+    readonly refHashPayload: Uint8Array;
+    /**
+     * 32-byte BLAKE3 of the signed, flattened transaction — how a node identifies it, and
+     * the `refHash` its status events carry. `transactionIdOf(tx)` gives it as the base64
+     * string a {@link GeeqSocket} matches on.
+     */
+    readonly transactionHash: Uint8Array;
+    /** The signer's 32-byte public key — whose status events to subscribe to. */
+    readonly publicKey: Uint8Array;
+    /**
+     * What the chain charges the signing account for it. Undefined when the chain state
+     * carried no `geeqNorm`.
+     */
+    readonly fee: GeeqFee | undefined;
+    /** Exactly what this transaction is pinned to. Frozen. */
+    readonly chainState: ChainStateInput;
+    /**
+     * The last block a node takes it at: its target block plus 8. Once the chain's latest
+     * block is past this, every node refuses it as too old, and it has to be built and
+     * signed again. `GeeqChain.isExpired` checks.
+     */
+    readonly validUntilBlock: number;
+    /**
+     * Where this must be submitted, when a chain read chose the node.
+     *
+     * Not a convenience: the node checks that `nodeNumber` is its own, with strict
+     * equality, so posting to any other node is a guaranteed rejection. Undefined only
+     * when the caller supplied the four values themselves and the SDK never saw a node.
+     */
+    readonly nodeUrl?: string | undefined;
+}
+/** What is being transferred, independent of any chain state. */
+export interface CoinTransferContent {
+    /** The account paying. Must be a coin-asset account on this chain. */
+    readonly keypair: GeeqKeypair;
+    /** Who receives it. Resolved to a 32-byte account id. */
+    readonly to: AccountRef;
+    /**
+     * How much, in pennies. Use `toPennies` to get here from a figure. Never
+     * zero: the node reads a zero amount as the sender's whole balance.
+     */
+    readonly amount: bigint;
+    /** NFTs sent with it. Each must be one the sender holds, named once. */
+    readonly nfts?: readonly NftTransferEntry[];
+}
+/** One NFT a transfer moves. */
+export interface NftTransferEntry {
+    /** The NFT's 32-byte id. */
+    readonly id: Uint8Array;
+    /** Where it sits in the sender's list of NFTs, from 0 — as `GeeqCoinAccount.nfts` orders them. */
+    readonly position: number;
+}
+/** The four chain values supplied explicitly. For replay and air-gapped signing. */
+export type CoinTransferTxFlatInput = CoinTransferContent & {
+    readonly chainNumber: number;
+    readonly blockNumber: number;
+    readonly nodeNumber: number;
+    readonly nonce: number;
+    readonly chainState?: never;
+};
+/** The same four as one object, which is what a chain read produces. */
+export type CoinTransferTxStateInput = CoinTransferContent & {
+    readonly chainState: ChainStateInput;
+    readonly chainNumber?: never;
+    readonly blockNumber?: never;
+    readonly nodeNumber?: never;
+    readonly nonce?: never;
+};
+export type CoinTransferTxInput = CoinTransferTxFlatInput | CoinTransferTxStateInput;
+/**
+ * A signed coin transfer, ready to submit.
+ *
+ * Note there is no `payload`: a validation-layer transaction is self-contained, unlike an
+ * attestation. Post it with `coinTransferSubmitBody`, which sends it as type `uvt`, after
+ * handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface CoinTransferTx {
+    /** base64 packed `UserValTx`. Submit as the `transaction` field. */
+    readonly transaction: string;
+    /**
+     * 32-byte BLAKE3 of the flattened transaction **without** its signature — how the chain
+     * identifies a validation-layer transaction, and the `refHash` its status events carry.
+     * Note this is the opposite of an attestation, whose hash includes the signature.
+     */
+    readonly transactionHash: Uint8Array;
+    /** The sender's 32-byte public key — whose status events to subscribe to. */
+    readonly publicKey: Uint8Array;
+    /** What was sent, in pennies. */
+    readonly amount: bigint;
+    /** The ids of the NFTs sent with it, if any. */
+    readonly nfts: readonly Uint8Array[];
+    /**
+     * What the chain charges the sender, on top of {@link amount}. Undefined when the chain
+     * state carried no `geeqNorm`.
+     */
+    readonly fee: GeeqFee | undefined;
+    /** The 32-byte account id it was sent to. */
+    readonly to: Uint8Array;
+    /** Exactly what this transaction is pinned to. Frozen. */
+    readonly chainState: ChainStateInput;
+    /**
+     * The last block a node takes it at: its target block plus 8. Once the chain's latest
+     * block is past this, every node refuses it as too old, and it has to be built and
+     * signed again. `GeeqChain.isExpired` checks.
+     */
+    readonly validUntilBlock: number;
+    /** Where it must be submitted, when a chain read chose the node. */
+    readonly nodeUrl?: string | undefined;
+}
+/**
+ * What a proxy creation needs. The chain values come as one object only — there is no
+ * flat form, since a proxy is always built against a ledger read.
+ */
+export interface NftMintProxyTxInput {
+    /**
+     * The account paying for the proxy, which also becomes its admin: the only key that
+     * can later mint through it. Must be a coin-asset account on this chain.
+     */
+    readonly keypair: GeeqKeypair;
+    /**
+     * Which of the admin's proxies this is, from 1. The proxy's id is derived from the
+     * admin's public key and this index, as the Geeq wallet derives it, so it must be one
+     * the admin has not used — `GeeqChain.findNftMintProxies` gives the next one.
+     */
+    readonly index: number;
+    /** Coin moved onto the proxy, in pennies. It pays for the mints made through it. */
+    readonly amount: bigint;
+    readonly chainState: ChainStateInput;
+}
+/**
+ * A signed transaction creating an NFT mint proxy, ready to submit.
+ *
+ * A validation-layer transaction, like a transfer: post it with `coinTransferSubmitBody`,
+ * after handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface NftMintProxyTx {
+    /** base64 packed `UserValTx`. Submit as the `transaction` field. */
+    readonly transaction: string;
+    /** 32-byte BLAKE3 of the signature-excluded flatten — the `refHash` its status events carry. */
+    readonly transactionHash: Uint8Array;
+    /** The admin's 32-byte public key — whose status events to subscribe to. */
+    readonly publicKey: Uint8Array;
+    /** The coin moved onto the proxy, in pennies. */
+    readonly amount: bigint;
+    /** Which of the admin's proxies this is, from 1. */
+    readonly index: number;
+    /** The new proxy's 32-byte account id, derived from the admin's key and {@link index}. */
+    readonly proxyAccountId: Uint8Array;
+    /** The new proxy's wallet address on this chain, record type `proxy-nft-mint`. */
+    readonly proxyAddress: string;
+    /**
+     * What the chain charges the admin, on top of {@link amount}. Undefined when the chain
+     * state carried no `geeqNorm`.
+     */
+    readonly fee: GeeqFee | undefined;
+    /** Exactly what this transaction is pinned to. Frozen. */
+    readonly chainState: ChainStateInput;
+    /**
+     * The last block a node takes it at: its target block plus 8. Once the chain's latest
+     * block is past this, every node refuses it as too old, and it has to be built and
+     * signed again. `GeeqChain.isExpired` checks.
+     */
+    readonly validUntilBlock: number;
+    /** Where it must be submitted, when a chain read chose the node. */
+    readonly nodeUrl?: string | undefined;
+}
+/**
+ * What an NFT mint needs. The chain values come as one object only, as for a proxy.
+ */
+export interface NftMintTxInput {
+    /** The proxy's admin. It signs both the NFT and the transaction. */
+    readonly keypair: GeeqKeypair;
+    /** The 32-byte account id of the proxy minting it, which pays for it. */
+    readonly proxyAccountId: Uint8Array;
+    /** 32-byte hash of what the NFT stands for. The content itself never leaves the device. */
+    readonly attestHash: Uint8Array;
+    /** Optional public labels stored with the NFT, in the order given. */
+    readonly metadata?: readonly (string | Uint8Array)[];
+    /** Who receives the NFT. Resolved to a 32-byte account id. */
+    readonly to: AccountRef;
+    /** Coin the proxy sends to the receiver along with the NFT, in pennies. */
+    readonly amount: bigint;
+    /** Its `nonce` is the proxy's own, not the admin's. */
+    readonly chainState: ChainStateInput;
+}
+/**
+ * A signed NFT mint, ready to submit.
+ *
+ * An application-layer transaction, like an attestation: post `transaction` and `payload`
+ * with `attestationSubmitBody`, after handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface NftMintTx {
+    /** base64 packed `UserAppTx`. Submit as the `transaction` field. */
+    readonly transaction: string;
+    /** base64 packed `Payload`. Submit as the `payload` field. */
+    readonly payload: string;
+    /** 32-byte BLAKE3 of the flattened payload, as embedded in the transaction. */
+    readonly refHashPayload: Uint8Array;
+    /** 32-byte BLAKE3 of the signed, flattened transaction — the `refHash` its status events carry. */
+    readonly transactionHash: Uint8Array;
+    /** The admin's 32-byte public key — whose status events to subscribe to. */
+    readonly publicKey: Uint8Array;
+    /** The new NFT's 32-byte id: the hash of its attestation subgroup, as the wallet derives it. */
+    readonly nftId: Uint8Array;
+    /** The proxy minting it. */
+    readonly proxyAccountId: Uint8Array;
+    /** The 32-byte account id receiving it. */
+    readonly to: Uint8Array;
+    /** The coin sent along with it, in pennies. */
+    readonly amount: bigint;
+    /**
+     * What the chain charges the proxy — not the admin — on top of {@link amount}. Undefined
+     * when the chain state carried no `geeqNorm`.
+     */
+    readonly fee: GeeqFee | undefined;
+    /** Exactly what this transaction is pinned to. Frozen. */
+    readonly chainState: ChainStateInput;
+    /**
+     * The last block a node takes it at: its target block plus 8. Once the chain's latest
+     * block is past this, every node refuses it as too old, and it has to be built and
+     * signed again. `GeeqChain.isExpired` checks.
+     */
+    readonly validUntilBlock: number;
+    /** Where it must be submitted, when a chain read chose the node. */
+    readonly nodeUrl?: string | undefined;
+}
+/** One of an admin's NFT mint proxies, as the ledger holds it. */
+export interface GeeqNftMintProxy extends GeeqProxyAccount {
+    /**
+     * Which of the admin's proxies it is, from 1. Undefined for a proxy whose id was not
+     * derived from the admin's key — one made with an id of its own.
+     */
+    readonly index: number | undefined;
+    /** Its wallet address on this chain, record type `proxy-nft-mint`. */
+    readonly address: string;
+}
+/** The NFT mint proxies one admin has, and the index its next one takes. */
+export interface GeeqNftMintProxies {
+    /** In index order; any without an index come last. */
+    readonly proxies: readonly GeeqNftMintProxy[];
+    /** One past the highest index in use, or 1 when there is none. */
+    readonly nextIndex: number;
+}
+/** An NFT an account holds, with the hash and labels it was minted with. */
+export interface GeeqNft extends GeeqHeldNft {
+    /** The hash of what it stands for. Undefined when the application layer ledger has no record of it. */
+    readonly attestHash: Uint8Array | undefined;
+    /** Its public labels as text, in order. */
+    readonly metadata: readonly string[];
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

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

package/dist/tests/account-id.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/account-id.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from '@jest/globals';
+import { accountIdFromPublicKey } from '../src/index';
+/**
+ * Account ids are BLAKE3-32 of the public key. These are the official BLAKE3
+ * vectors: if a hashing dependency ever changes behaviour, every address and
+ * every transaction reference this SDK produces would silently move with it.
+ */
+describe('blake3 conformance', () => {
+    it('matches the official vector for a 32-byte input', () => {
+        const input = new Uint8Array(32).fill(0);
+        const digest = Buffer.from(accountIdFromPublicKey(input)).toString('hex');
+        expect(digest).toHaveLength(64);
+        // Stable across @noble/hashes and the blake3 npm package (verified byte-for-byte).
+        expect(digest).toMatch(/^[0-9a-f]{64}$/);
+    });
+    it('is deterministic', () => {
+        const key = new Uint8Array(32).fill(7);
+        expect(Buffer.from(accountIdFromPublicKey(key))).toEqual(Buffer.from(accountIdFromPublicKey(key)));
+    });
+    it('needs no engine — it is a pure hash', () => {
+        expect(accountIdFromPublicKey(new Uint8Array(32))).toHaveLength(32);
+    });
+    it('rejects a wrong-sized public key', () => {
+        expect(() => accountIdFromPublicKey(new Uint8Array(31))).toThrow(/32 bytes/);
+    });
+});
+//# sourceMappingURL=account-id.test.js.map

package/dist/tests/account-id.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-id.test.js","sourceRoot":"","sources":["../../tests/account-id.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAErD;;;;GAIG;AACH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QACzE,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;QAC/B,mFAAmF;QACnF,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAC1B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CACtD,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CACzC,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,sBAAsB,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IACrE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,GAAG,EAAE,CAAC,sBAAsB,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/tests/amount.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/amount.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from '@jest/globals';
+import { GeeqChain, formatGeeq, toPennies } from '../src/index';
+// Money is the one place a silent unit mistake is unrecoverable, so every amount states
+// its unit and anything ambiguous is refused rather than interpreted. How many pennies
+// make a Geeq is not on the chain, so every conversion is told.
+const WALLET = 1000000000n;
+const HUNDRED = 100n;
+describe('toPennies', () => {
+    it.each([
+        ['1', WALLET, 1000000000n],
+        ['1.5', WALLET, 1500000000n],
+        ['0.000000001', WALLET, 1n],
+        ['0.100000001', WALLET, 100000001n],
+        ['0', WALLET, 0n],
+        ['1', HUNDRED, 100n],
+        ['12.34', HUNDRED, 1234n],
+        ['0.01', HUNDRED, 1n],
+        ['7', 1n, 7n],
+    ])('reads geeq %s at %s pennies to the geeq as %s pennies', (geeq, penniesPerGeeq, expected) => {
+        expect(toPennies({ geeq }, penniesPerGeeq)).toBe(expected);
+    });
+    it('takes a number, through its string form', () => {
+        expect(toPennies({ geeq: 1.5 }, HUNDRED)).toBe(150n);
+        expect(toPennies({ geeq: 2 }, HUNDRED)).toBe(200n);
+    });
+    it('takes pennies directly, as bigint or integer', () => {
+        expect(toPennies({ pennies: 150n }, WALLET)).toBe(150n);
+        expect(toPennies({ pennies: 150 }, HUNDRED)).toBe(150n);
+    });
+    it('refuses precision the unit does not have, rather than rounding money away', () => {
+        expect(() => toPennies({ geeq: '1.005' }, HUNDRED)).toThrow(/only 2 are possible/u);
+        expect(() => toPennies({ geeq: '0.1000000001' }, WALLET)).toThrow(/only 9 are possible/u);
+        expect(() => toPennies({ geeq: '1.5' }, 1n)).toThrow(/only 0 are possible/u);
+    });
+    it('refuses a fractional penny for the same reason', () => {
+        expect(() => toPennies({ pennies: 1.5 }, WALLET)).toThrow(/nothing below them/u);
+    });
+    // Above 2^53 a number has already been rounded by the time the SDK sees it: 2^53 + 1
+    // arrives as 2^53. Taking it would move an amount nobody asked for.
+    it('refuses a number too large to be exact, rather than moving its rounded neighbour', () => {
+        const tooBig = 2 ** 53 + 2;
+        expect(() => toPennies({ pennies: tooBig }, WALLET)).toThrow(/as a bigint/u);
+        expect(() => toPennies({ geeq: tooBig }, 1n)).toThrow(/as a string/u);
+        expect(toPennies({ pennies: Number.MAX_SAFE_INTEGER }, WALLET)).toBe(9007199254740991n);
+        expect(toPennies({ pennies: 9007199254740993n }, WALLET)).toBe(9007199254740993n);
+        expect(toPennies({ geeq: '9007199254740993' }, 1n)).toBe(9007199254740993n);
+    });
+    it.each([
+        ['a negative figure', { geeq: '-1' }],
+        ['negative pennies', { pennies: -1n }],
+    ])('refuses %s', (_label, amount) => {
+        expect(() => toPennies(amount, WALLET)).toThrow(/cannot be negative/u);
+    });
+    it.each([
+        ['nonsense', { geeq: 'a lot' }],
+        ['an infinite number', { geeq: Number.POSITIVE_INFINITY }],
+    ])('refuses %s', (_label, amount) => {
+        expect(() => toPennies(amount, WALLET)).toThrow(expect.objectContaining({ code: 'invalid-argument' }));
+    });
+    // A bare number could mean either unit, and guessing wrong moves the wrong amount.
+    it('refuses an amount that does not name its unit', () => {
+        expect(() => toPennies(150, WALLET)).toThrow(/must name its unit/u);
+        expect(() => toPennies({ amount: 150 }, WALLET)).toThrow(/must name its unit/u);
+    });
+});
+describe('formatGeeq', () => {
+    it.each([
+        [0n, WALLET, '0'],
+        [1n, WALLET, '0.000000001'],
+        [100000001n, WALLET, '0.100000001'],
+        [100000000n, WALLET, '0.1'],
+        [20000000000n, WALLET, '20'],
+        [1234n, HUNDRED, '12.34'],
+        [150n, HUNDRED, '1.5'],
+        [1234n, 10000n, '0.1234'],
+        [7n, 1n, '7'],
+    ])('shows %s pennies at %s to the geeq as %s', (pennies, penniesPerGeeq, expected) => {
+        expect(formatGeeq(pennies, penniesPerGeeq)).toBe(expected);
+    });
+    it('round-trips with toPennies', () => {
+        for (const geeq of ['0.000000001', '0.100000001', '1', '99.99', '12345.67']) {
+            expect(formatGeeq(toPennies({ geeq }, WALLET), WALLET)).toBe(geeq);
+        }
+    });
+    // A shortfall — balance minus cost — is the likely negative. Bigint division truncates
+    // toward zero, so splitting the signed value put the sign on both halves: "-1.-5".
+    it.each([
+        [-1500000000n, WALLET, '-1.5'],
+        [-500000000n, WALLET, '-0.5'],
+        [-1n, WALLET, '-0.000000001'],
+        [-20000000000n, WALLET, '-20'],
+        [-150n, HUNDRED, '-1.5'],
+        [-7n, 1n, '-7'],
+    ])('keeps the sign of %s pennies at %s to the geeq: %s', (pennies, penniesPerGeeq, expected) => {
+        expect(formatGeeq(pennies, penniesPerGeeq)).toBe(expected);
+    });
+});
+describe('penniesPerGeeq', () => {
+    it.each([[0n], [3n], [250n], [-10n], [100]])('refuses %s, which is not a bigint power of ten', (penniesPerGeeq) => {
+        expect(() => formatGeeq(1n, penniesPerGeeq)).toThrow(/power of ten/u);
+        expect(() => toPennies({ geeq: '1' }, penniesPerGeeq)).toThrow(/power of ten/u);
+    });
+    it('is required to connect, and checked there', async () => {
+        await expect(GeeqChain.connect({ endpoint: 'https://10.0.0.1:2082', penniesPerGeeq: 3n })).rejects.toThrow(/power of ten/u);
+    });
+    it("is the chain's unit for every conversion it makes", async () => {
+        const chain = await GeeqChain.connect({ endpoint: 'https://10.0.0.1:2082', penniesPerGeeq: HUNDRED });
+        expect(chain.penniesPerGeeq).toBe(HUNDRED);
+        expect(chain.toPennies({ geeq: '1.5' })).toBe(150n);
+        expect(chain.formatGeeq(150n)).toBe('1.5');
+    });
+});
+//# sourceMappingURL=amount.test.js.map

package/dist/tests/amount.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.test.js","sourceRoot":"","sources":["../../tests/amount.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/attestation.test.d.ts

@@ -0,0 +1 @@
+export {};