@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/types/index.js

@@ -1,4 +1,5 @@
-export { AES_AUTH_TAG_LENGTH, AES_IV_LENGTH, AES_KEY_LENGTH, AES_METADATA_OVERHEAD, BASE85_LIMB_MAX, BN254_FIELD_PRIME, CURVE25519_FIELD_PRIME, CryptographyAssertionError, DAY_MAX, DAY_MIN, GROTH16_G1_BYTE_LENGTH, GROTH16_G2_BYTE_LENGTH, HOUR_MAX, HOUR_MIN, I1024_MAX, I1024_MIN, I128_MAX, I128_MIN, I16_MAX, I16_MIN, I256_MAX, I256_MIN, I32_MAX, I32_MIN, I512_MAX, I512_MIN, I64_MAX, I64_MIN, I8_MAX, I8_MIN, MINUTE_MAX, MINUTE_MIN, MONTH_MAX, MONTH_MIN, MathematicsAssertionError, OPTIONAL_DATA_BYTE_LENGTH, SECOND_MAX, SECOND_MIN, SIGNATURE_BYTE_LENGTH, SolanaAssertionError, TemporalAssertionError, U1024_BYTE_LENGTH, U1024_MAX, U128_BYTE_LENGTH, U128_MAX, U16_BYTE_LENGTH, U16_MAX, U256_BYTE_LENGTH, U256_MAX, U32_BYTE_LENGTH, U32_MAX, U512_BYTE_LENGTH, U512_MAX, U64_BYTE_LENGTH, U64_MAX, U8_BYTE_LENGTH, U8_MAX, X25519_BYTE_LENGTH, YEAR_MAX, YEAR_MIN, ZK_PROOF_BYTE_LENGTH, asRelayableSignedTransaction, assertAesCiphertextWithMetadata, assertAesKey, assertAesPlaintext, assertBase85Limb, assertBeBytes, assertBn254FieldElement, assertBytes, assertCurve25519FieldElement, assertDailyViewingKey, assertDay, assertGenerationSeed, assertGroth16ProofA, assertGroth16ProofB, assertGroth16ProofC, assertHour, assertHourlyViewingKey, assertI1024, assertI128, assertI16, assertI256, assertI32, assertI512, assertI64, assertI8, assertKeccak256Hash, assertKeccak512Hash, assertLeBytes, assertMasterSeed, assertMasterViewingKey, assertMintViewingKey, assertMinute, assertMinuteViewingKey, assertMonth, assertMonthlyViewingKey, assertOptionalData32, assertPoseidonCiphertext, assertPoseidonCounter, assertPoseidonHash, assertPoseidonKey, assertPoseidonKeystream, assertPoseidonPlaintext, assertRcCiphertext, assertRcCounter, assertRcEncryptionNonce, assertRcKey, assertRcPlaintext, assertSecond, assertSecondViewingKey, assertSharedSecret, assertSignatureBytes, assertSignedInteger, assertSolanaBytes, assertString, assertTimestampComponent, assertTransactionSignature, assertU1024, assertU1024BeBytes, assertU1024LeBytes, assertU128, assertU128BeBytes, assertU128LeBytes, assertU16, assertU16BeBytes, assertU16LeBytes, assertU256, assertU256BeBytes, assertU256LeBytes, assertU32, assertU32BeBytes, assertU32LeBytes, assertU512, assertU512BeBytes, assertU512LeBytes, assertU64, assertU64BeBytes, assertU64LeBytes, assertU8, assertU8BeBytes, assertU8LeBytes, assertUnsignedInteger, assertX25519Bytes, assertX25519Keypair, assertX25519PrivateKey, assertX25519PublicKey, assertYear, assertYearlyViewingKey, assertZkProofBytes } from '../chunk-BM7N6N7E.js';
+export { DAY_MAX, DAY_MIN, HOUR_MAX, HOUR_MIN, MINUTE_MAX, MINUTE_MIN, MONTH_MAX, MONTH_MIN, SECOND_MAX, SECOND_MIN, SIGNATURE_BYTE_LENGTH, SolanaAssertionError, TemporalAssertionError, YEAR_MAX, YEAR_MIN, asRelayableSignedTransaction, assertDay, assertHour, assertMinute, assertMonth, assertSecond, assertSignatureBytes, assertSolanaBytes, assertString, assertTimestampComponent, assertTransactionSignature, assertYear } from '../chunk-DD2WCK4C.js';
+export { AES_AUTH_TAG_LENGTH, AES_IV_LENGTH, AES_KEY_LENGTH, AES_METADATA_OVERHEAD, BASE85_LIMB_MAX, BN254_FIELD_PRIME, CURVE25519_FIELD_PRIME, CryptographyAssertionError, GROTH16_G1_BYTE_LENGTH, GROTH16_G2_BYTE_LENGTH, I1024_MAX, I1024_MIN, I128_MAX, I128_MIN, I16_MAX, I16_MIN, I256_MAX, I256_MIN, I32_MAX, I32_MIN, I512_MAX, I512_MIN, I64_MAX, I64_MIN, I8_MAX, I8_MIN, MathematicsAssertionError, OPTIONAL_DATA_BYTE_LENGTH, U1024_BYTE_LENGTH, U1024_MAX, U128_BYTE_LENGTH, U128_MAX, U16_BYTE_LENGTH, U16_MAX, U256_BYTE_LENGTH, U256_MAX, U32_BYTE_LENGTH, U32_MAX, U512_BYTE_LENGTH, U512_MAX, U64_BYTE_LENGTH, U64_MAX, U8_BYTE_LENGTH, U8_MAX, X25519_BYTE_LENGTH, ZK_PROOF_BYTE_LENGTH, assertAesCiphertextWithMetadata, assertAesKey, assertAesPlaintext, assertBase85Limb, assertBeBytes, assertBn254FieldElement, assertBytes, assertCurve25519FieldElement, assertDailyViewingKey, assertGenerationSeed, assertGroth16ProofA, assertGroth16ProofB, assertGroth16ProofC, assertHourlyViewingKey, assertI1024, assertI128, assertI16, assertI256, assertI32, assertI512, assertI64, assertI8, assertKeccak256Hash, assertKeccak512Hash, assertLeBytes, assertMasterSeed, assertMasterViewingKey, assertMintViewingKey, assertMinuteViewingKey, assertMonthlyViewingKey, assertOptionalData32, assertPoseidonCiphertext, assertPoseidonCounter, assertPoseidonHash, assertPoseidonKey, assertPoseidonKeystream, assertPoseidonPlaintext, assertRcCiphertext, assertRcCounter, assertRcEncryptionNonce, assertRcKey, assertRcPlaintext, assertSecondViewingKey, assertSharedSecret, assertSignedInteger, assertU1024, assertU1024BeBytes, assertU1024LeBytes, assertU128, assertU128BeBytes, assertU128LeBytes, assertU16, assertU16BeBytes, assertU16LeBytes, assertU256, assertU256BeBytes, assertU256LeBytes, assertU32, assertU32BeBytes, assertU32LeBytes, assertU512, assertU512BeBytes, assertU512LeBytes, assertU64, assertU64BeBytes, assertU64LeBytes, assertU8, assertU8BeBytes, assertU8LeBytes, assertUnsignedInteger, assertX25519Bytes, assertX25519Keypair, assertX25519PrivateKey, assertX25519PublicKey, assertYearlyViewingKey, assertZkProofBytes } from '../chunk-CFTW5WNG.js';
 import '../chunk-7QVYU63E.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/types-BohhvPth.d.cts

@@ -0,0 +1,87 @@
+import { S as SubSubBrandedType, f as U256 } from './types-C_V_CaKK.cjs';
+
+/**
+ * BN254 Field Element Types
+ *
+ * This module defines the foundational type primitives for working with elements
+ * of the BN254 (alt_bn128) prime field. BN254 is a pairing-friendly elliptic curve
+ * widely used in zero-knowledge proof systems, including Groth16, PLONK, and the
+ * Circom/SnarkJS toolchain. Ethereum natively supports BN254 via the EIP-196 and
+ * EIP-197 precompiles.
+ *
+ * @remarks
+ * The BN254 scalar field F_r is the prime field whose order is the `r`-order of
+ * points on the curve — i.e., the number of points on the curve's cyclic group.
+ * All arithmetic in ZK circuits (Circom constraints, Groth16 witness values, etc.)
+ * is performed modulo this prime. The prime has approximately 254 significant bits,
+ * providing roughly 127 bits of symmetric security.
+ *
+ * The branded type system used here (`SubSubBrandedType`) enforces at compile time
+ * that raw `bigint` values have been validated and reduced into the field. This
+ * prevents accidentally passing an unreduced value (e.g., a product before modular
+ * reduction) where a field element is expected.
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-196} EIP-196: Precompile for elliptic curve addition and scalar multiplication on alt_bn128
+ * @see {@link https://eips.ethereum.org/EIPS/eip-197} EIP-197: Precompile for optimal ate pairing check on alt_bn128
+ * @see {@link https://eprint.iacr.org/2010/354} Original BN curve construction paper
+ *
+ * @packageDocumentation
+ * @module math/bn254/types
+ */
+
+/**
+ * A type-safe branded representation of a BN254 (alt_bn128) scalar field element.
+ *
+ * BN254 is a pairing-friendly elliptic curve that is the foundation of Ethereum's
+ * SNARK precompiles and the Circom/Groth16 ecosystem. The scalar field F_r consists
+ * of all integers in the range `[0, BN254_FIELD_PRIME - 1]`.
+ *
+ * @remarks
+ * ## Why a Branded Type?
+ *
+ * A `bigint` can represent any integer, including values outside the field range.
+ * Using a branded type ensures that:
+ * 1. Only values that have been explicitly validated (via `assertBn254FieldElement`)
+ *    can be assigned to this type.
+ * 2. The TypeScript compiler will reject attempts to pass an arbitrary `bigint` where
+ *    a `Bn254FieldElement` is expected, catching a whole class of cryptographic bugs.
+ * 3. Intermediate values produced by field operations (e.g., `a * b` before reduction)
+ *    cannot be accidentally used as field elements.
+ *
+ * ## BN254 Curve Properties
+ *
+ * - Curve equation: `y^2 = x^3 + 3` over F_p (where p is the base field prime)
+ * - Scalar field order: `r = 21888242871839275222246405745257275088548364400416034343698204186575808495617`
+ * - Embedding degree: 12 (makes it pairing-friendly)
+ * - Security level: ~100 bits (conservative estimate accounting for NFS attacks on pairings)
+ * - Supported operations: Groth16 verification, Poseidon hashing, EdDSA (Baby Jubjub)
+ *
+ * ## Usage
+ *
+ * Values of this type are inputs and outputs of all field arithmetic functions in
+ * this module (`bn254Add`, `bn254Mul`, etc.) and the Poseidon hash functions.
+ *
+ * @see {@link assertBn254FieldElement} The assertion function that produces values of this type
+ * @see {@link BN254_FIELD_PRIME} The modulus that defines the field
+ * @see {@link https://eips.ethereum.org/EIPS/eip-196} EIP-196
+ *
+ * @example
+ * ```typescript
+ * import { type Bn254FieldElement, assertBn254FieldElement, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * // Validate and brand a known constant
+ * const one = 1n;
+ * assertBn254FieldElement(one, "one");
+ * // one is now typed as Bn254FieldElement
+ *
+ * // The type prevents mixing with plain bigint in function signatures
+ * function requiresFieldElement(x: Bn254FieldElement): void { /* ... *\/ }
+ * requiresFieldElement(42n); // TypeScript compile error
+ * requiresFieldElement(one); // OK
+ * ```
+ *
+ * @public
+ */
+type Bn254FieldElement = SubSubBrandedType<U256, "Bn254FieldElement">;
+
+export type { Bn254FieldElement as B };

package/dist/types-CW0oTT0j.d.ts

@@ -0,0 +1,87 @@
+import { S as SubSubBrandedType, f as U256 } from './types-C_V_CaKK.js';
+
+/**
+ * BN254 Field Element Types
+ *
+ * This module defines the foundational type primitives for working with elements
+ * of the BN254 (alt_bn128) prime field. BN254 is a pairing-friendly elliptic curve
+ * widely used in zero-knowledge proof systems, including Groth16, PLONK, and the
+ * Circom/SnarkJS toolchain. Ethereum natively supports BN254 via the EIP-196 and
+ * EIP-197 precompiles.
+ *
+ * @remarks
+ * The BN254 scalar field F_r is the prime field whose order is the `r`-order of
+ * points on the curve — i.e., the number of points on the curve's cyclic group.
+ * All arithmetic in ZK circuits (Circom constraints, Groth16 witness values, etc.)
+ * is performed modulo this prime. The prime has approximately 254 significant bits,
+ * providing roughly 127 bits of symmetric security.
+ *
+ * The branded type system used here (`SubSubBrandedType`) enforces at compile time
+ * that raw `bigint` values have been validated and reduced into the field. This
+ * prevents accidentally passing an unreduced value (e.g., a product before modular
+ * reduction) where a field element is expected.
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-196} EIP-196: Precompile for elliptic curve addition and scalar multiplication on alt_bn128
+ * @see {@link https://eips.ethereum.org/EIPS/eip-197} EIP-197: Precompile for optimal ate pairing check on alt_bn128
+ * @see {@link https://eprint.iacr.org/2010/354} Original BN curve construction paper
+ *
+ * @packageDocumentation
+ * @module math/bn254/types
+ */
+
+/**
+ * A type-safe branded representation of a BN254 (alt_bn128) scalar field element.
+ *
+ * BN254 is a pairing-friendly elliptic curve that is the foundation of Ethereum's
+ * SNARK precompiles and the Circom/Groth16 ecosystem. The scalar field F_r consists
+ * of all integers in the range `[0, BN254_FIELD_PRIME - 1]`.
+ *
+ * @remarks
+ * ## Why a Branded Type?
+ *
+ * A `bigint` can represent any integer, including values outside the field range.
+ * Using a branded type ensures that:
+ * 1. Only values that have been explicitly validated (via `assertBn254FieldElement`)
+ *    can be assigned to this type.
+ * 2. The TypeScript compiler will reject attempts to pass an arbitrary `bigint` where
+ *    a `Bn254FieldElement` is expected, catching a whole class of cryptographic bugs.
+ * 3. Intermediate values produced by field operations (e.g., `a * b` before reduction)
+ *    cannot be accidentally used as field elements.
+ *
+ * ## BN254 Curve Properties
+ *
+ * - Curve equation: `y^2 = x^3 + 3` over F_p (where p is the base field prime)
+ * - Scalar field order: `r = 21888242871839275222246405745257275088548364400416034343698204186575808495617`
+ * - Embedding degree: 12 (makes it pairing-friendly)
+ * - Security level: ~100 bits (conservative estimate accounting for NFS attacks on pairings)
+ * - Supported operations: Groth16 verification, Poseidon hashing, EdDSA (Baby Jubjub)
+ *
+ * ## Usage
+ *
+ * Values of this type are inputs and outputs of all field arithmetic functions in
+ * this module (`bn254Add`, `bn254Mul`, etc.) and the Poseidon hash functions.
+ *
+ * @see {@link assertBn254FieldElement} The assertion function that produces values of this type
+ * @see {@link BN254_FIELD_PRIME} The modulus that defines the field
+ * @see {@link https://eips.ethereum.org/EIPS/eip-196} EIP-196
+ *
+ * @example
+ * ```typescript
+ * import { type Bn254FieldElement, assertBn254FieldElement, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * // Validate and brand a known constant
+ * const one = 1n;
+ * assertBn254FieldElement(one, "one");
+ * // one is now typed as Bn254FieldElement
+ *
+ * // The type prevents mixing with plain bigint in function signatures
+ * function requiresFieldElement(x: Bn254FieldElement): void { /* ... *\/ }
+ * requiresFieldElement(42n); // TypeScript compile error
+ * requiresFieldElement(one); // OK
+ * ```
+ *
+ * @public
+ */
+type Bn254FieldElement = SubSubBrandedType<U256, "Bn254FieldElement">;
+
+export type { Bn254FieldElement as B };