multifactor_test.abi.json

Overview

This file defines the Application Binary Interface (ABI) for a smart contract focused on multifactor authentication and secure transaction management. It specifies the contract's versioning, data fields, and an extensive set of functions that enable management of cryptographic keys, zero-knowledge proof (ZKP) factors, recovery mechanisms, security cards, and transaction lifecycle operations. The contract is designed to maintain a layered security model by integrating cryptographic proofs, key rotations, and multifactor authentication elements.

The ABI version is 2, with contract version 2.4. The contract maintains persistent state variables such as cryptographic keys, timestamps, security card mappings, and transaction records.

Fields

The contract stores several fields representing cryptographic keys, state flags, collections for multifactor elements, and transaction data:

• _pubkey (uint256): The public key representing the contract owner.

• _timestamp (uint64): Timestamp for the last update or event.

• _constructorFlag (bool): Flag indicating if constructor has been called.

• _factors_ordered_by_timestamp (map(uint256,uint256)): Maps timestamps to factor identifiers, tracking factors by creation time.

• _factors_len (uint8): Number of active factors.

• _owner_pubkey (uint256): Current owner’s public key.

• _candidate_new_owner_pubkey_and_expiration (optional(tuple(uint256,uint64))): Optional tuple for candidate owner and expiration.

• _pub_recovery_key (uint256): Public key used for recovery operations.

• _jwk_update_key (uint256): Key for updating JSON Web Key (JWK) moduli.

• _root_provider_certificates (map(uint256,bytes)): Root certificates indexed by serial number.

• _jwk_modulus_data (map(uint256,tuple(bytes,uint64))): Maps key IDs to JWK modulus bytes and their expiration timestamps.

• _jwk_modulus_data_len (uint8): Number of JWK moduli stored.

• _start_point_jwk (optional(tuple(uint256,tuple(bytes,uint64)))): Optional starting JWK data with key ID and modulus.

• _zkid (string): Zero-knowledge identifier string.

• _index_mod_4 (uint8): Index modulo 4, likely used for sharding or partitioning.

• _iss_base_64 (string): Base64-encoded issuer identifier.

• _lv_provider_bytes (bytes): Byte representation of the provider.

• _use_security_card (bool): Flag indicating whether security cards are active.

• _m_security_cards (map(uint256,bool)): Maps public keys to boolean indicating security card presence.

• _m_security_cards_len (uint8): Number of security cards.

• _m_transactions (map(uint64,tuple)): Maps transaction IDs to transaction details (id, creator, destination, value, custom coins, flags, payload, bounce).

• _m_transactions_len (uint8): Number of transactions stored.

• _min_value (uint128): Minimum value threshold for certain operations.

• _max_cleanup_txns (uint256): Maximum number of transactions to clean up.

• _force_remove_oldest (bool): Flag to force removal of the oldest elements.

• _verification_key_index (uint32): Index of the verification key.

• _wasm_hash (bytes): Hash of the WASM code associated with the contract.

Functions

Constructor

constructor

Initializes the contract with multifactor authentication parameters and cryptographic keys.

Inputs:

• zkid (string): Zero-knowledge identifier.

• proof (bytes): Cryptographic proof bytes.

• epk (uint256): Ephemeral public key.

• epk_sig (bytes): Signature for ephemeral public key.

• epk_expire_at (uint64): Expiration timestamp for the ephemeral public key.

• jwk_modulus (bytes): Modulus part of the JWK.

• kid (bytes): Key ID for the JWK modulus.

• jwk_modulus_expire_at (uint64): Expiration timestamp for the JWK modulus.

• index_mod_4 (uint8): Index modulo 4 for internal partitioning.

• iss_base_64 (string): Base64 encoded issuer string.

• provider (string): Provider identifier.

• header_base_64 (string): Base64 encoded header.

• pub_recovery_key (uint256): Public recovery key.

• pub_recovery_key_sig (bytes): Signature for the recovery key.

• jwk_update_key (uint256): Key used to update JWK moduli.

• jwk_update_key_sig (bytes): Signature for the JWK update key.

• value (uint64): Initial value associated with the contract.

• root_provider_certificates (map(uint256,bytes)): Map of root provider certificates by serial number.

Outputs: None

Usage Example:

{
  "zkid": "zk123",
  "proof": "...",
  "epk": 123456789,
  "epk_sig": "...",
  "epk_expire_at": 1680000000,
  "jwk_modulus": "...",
  "kid": "...",
  "jwk_modulus_expire_at": 1680000000,
  "index_mod_4": 2,
  "iss_base_64": "issuerBase64",
  "provider": "providerName",
  "header_base_64": "headerBase64",
  "pub_recovery_key": 987654321,
  "pub_recovery_key_sig": "...",
  "jwk_update_key": 111222333,
  "jwk_update_key_sig": "...",
  "value": 100,
  "root_provider_certificates": {"1": "...", "2": "..."}
}

JWK Modulus Management

• addJwkModulus(root_cert_sn: uint256, lv_kid: bytes, tls_data: bytes) -> bool

  Adds a new JWK modulus after verifying it against a root certificate serial number.

• deleteJwkModulusByUpdateJwkKey(kid: bytes)

  Deletes a JWK modulus identified by its key ID, authorized by the JWK update key.

• deleteJwkModulus(kid: bytes)

  Deletes a JWK modulus by its key ID.

• cleanAllExpiredJwks(epk_expire_at: uint64)

  Cleans all JWK moduli that have expired before or at the given timestamp.

• deleteJwkModulusByFactor(epk_expire_at: uint64, kid: bytes)

  Deletes a JWK modulus associated with a factor and expiration time.

• addJwkModulusOnlyForTest(kid: bytes, jwk_modulus_expire_at: uint64, jwk_modulus: bytes)

  Test-only function to add a JWK modulus without validation.

Zero-Knowledge Proof (ZKP) Factor Management

• addZKPfactor(proof: bytes, epk: uint256, kid: bytes, header_base_64: string, epk_expire_at: uint64) -> bool

  Adds a ZKP factor with the given proof and keys.

• deleteZKPfactorByItself(epk_expire_at: uint64)

  Deletes a ZKP factor by its expiration timestamp.

• cleanAllExpiredZKPFactors(epk_expire_at: uint64)

  Cleans all expired ZKP factors before or at the given timestamp.

• deleteZKPfactor(epk_expire_at: uint64, epk: uint256)

  Deletes a specific ZKP factor based on expiration and ephemeral public key.

• deleteZKPfactor_(epk: uint256)

  Deletes a ZKP factor by ephemeral public key (underscore suffix suggests internal use).

• addZKPfactorOnlyForTest(epk: uint256, epk_expire_at: uint64) -> bool

  Test-only function to add a ZKP factor.

Security Card Management

• addSecurityCard(pubkey: uint256, pubkey_sig: bytes)

  Adds a security card identified by a public key and its signature.

• deleteSecurityCard(pubkey: uint256)

  Deletes a security card by its public key.

• turnOffSecurityCards()

  Deactivates all security cards.

• turnOnSecurityCards()

  Reactivates security cards.

• deleteAllSecurityCards()

  Removes all security cards.

Seed Phrase and Recovery Management

• updateRecoveryPhrase(new_pub_recovery_key: uint256, new_pub_recovery_key_sig: bytes)

  Updates the recovery phrase with a new public recovery key and signature.

• updateJwkUpdateKey(new_jwk_update_key: uint256, new_jwk_update_key_sig: bytes)

  Updates the key used for JWK modulus updates.

• updateZkid(...)

  Updates the zero-knowledge identifier and associated cryptographic data.

• updateSeedPhrase(new_owner_pubkey: uint256, new_owner_pubkey_sig: bytes)

  Updates the seed phrase with a new owner public key and signature.

• changeSeedPhrase(epk_expire_at: uint64, new_owner_pubkey: uint256, new_owner_pubkey_sig: bytes)

  Initiates changing the seed phrase with expiration and verification.

• acceptCandidateSeedPhrase(new_owner_pubkey: uint256)

  Accepts a candidate new owner’s seed phrase.

• deleteCandidateSeedPhrase(epk_expire_at: uint64)

  Deletes a candidate seed phrase pending acceptance.

Transaction Management

• sendTransaction(epk_expire_at: uint64, dest: address, value: uint128, cc: map(uint32,varuint32), bounce: bool, flags: uint8, payload: cell) -> address

  Sends a transaction to a destination address with given parameters and returns the resulting address.

• submitTransaction(epk_expire_at: uint64, dest: address, value: uint128, cc: map(uint32,varuint32), bounce: bool, allBalance: bool, payload: cell) -> uint64

  Submits a transaction and returns the transaction ID.

• confirmTransaction(transactionId: uint64)

  Confirms a previously submitted transaction by its ID.

• exchangeToken(epk_expire_at: uint64, value: uint64)

  Exchanges tokens with expiration control.

• exchangeTokenWithOwner(value: uint64)

  Exchanges tokens associated with the contract owner.

• setMaxCleanupTxns(epk_expire_at: uint64, value: uint256)

  Sets the maximum number of cleanup transactions.

• setMinValue(epk_expire_at: uint64, value: uint128)

  Sets the minimum acceptable value for transactions or other operations.

• getTransaction(transactionId: uint64) -> tuple

  Retrieves details of a transaction by ID.

• getTransactions() -> tuple[]

  Retrieves all transactions stored.

• getTransactionIds() -> uint64[]

  Retrieves all transaction IDs.

Accessors / Getters

• _factors_ordered_by_timestamp() -> map(uint256,uint256)

• _factors_len() -> uint8

• _owner_pubkey() -> uint256

• _pub_recovery_key() -> uint256

• _jwk_update_key() -> uint256

• _root_provider_certificates() -> map(uint256,bytes)

• _jwk_modulus_data() -> map(uint256,tuple(bytes,uint64))

• _jwk_modulus_data_len() -> uint8

• _zkid() -> string

• _index_mod_4() -> uint8

• _iss_base_64() -> string

• _lv_provider_bytes() -> bytes

• _use_security_card() -> bool

• _m_security_cards() -> map(uint256,bool)

• _m_security_cards_len() -> uint8

• _m_transactions() -> map(uint64,tuple)

• _m_transactions_len() -> uint8

• _min_value() -> uint128

• _max_cleanup_txns() -> uint256

• _force_remove_oldest() -> bool

• _verification_key_index() -> uint32

• _wasm_hash() -> bytes

• getZKPEphemeralPublicKeys() -> uint256[]

  Returns a list of ephemeral public keys associated with ZKP factors.

• getTimeStamp() -> uint32

  Returns the current contract timestamp.

• getSecurityCardKeys() -> uint256[]

  Returns all public keys associated with security cards.

• get_epk_expire_at(epk: uint256) -> uint64

  Retrieves the expiration timestamp for a given ephemeral public key.

• getVersion() -> (string, string)

  Returns the ABI version and contract version strings.

Important Implementation Details and Algorithms

• Zero-Knowledge Proof (ZKP) Integration: The contract manages ephemeral public keys and proofs to validate multifactor authentication factors without revealing sensitive information, employing zero-knowledge proof mechanisms. ZKP factors are tightly controlled by expiration timestamps and cryptographic signatures.

• JWK Modulus Lifecycle: JWK moduli are stored with expiration times and can be added, deleted, or cleaned up based on their validity period. Root provider certificates authorize adding new JWK moduli to ensure trust.

• Security Cards: The contract supports enabling/disabling security cards, which provide an additional authentication factor. Security cards are managed as a map of public keys with boolean flags.

• Transaction Confirmation Workflow: Transactions are submitted and later confirmed, allowing multi-step verification. Custom coins and flags can be specified per transaction, with payloads encapsulated using a cell data structure.

• Recovery and Seed Phrase Updates: The contract supports updating recovery keys and seed phrases through a controlled process involving candidate acceptance and signature verification, enhancing the security of ownership transfer.

• Cleanup and Limits: To maintain performance and manage storage, the contract includes cleanup functions for expired JWKs, ZKP factors, and transactions, with configurable limits on the max number of cleanup transactions and force removal flags.

• Versioning and WASM Hashing: The contract exposes its version and the hash of the associated WASM code to ensure integrity and support upgrades.

Interaction with Other System Components

• Root Provider Certificates: The contract relies on root provider certificates for validation of keys and certificates, integrating with external certificate authorities or providers.

• Cryptographic Proofs and Signatures: Inputs such as proofs, signatures, and public keys imply interaction with cryptographic libraries or subsystems handling signature verification and zero-knowledge proof validation.

• Transaction Layer: The contract interacts with the blockchain or ledger to send, submit, confirm, and exchange tokens via transactions, interfacing with the underlying transaction management system.

• Security Cards: Security card management suggests integration with hardware or software tokens used for multifactor authentication.

• WASM Environment: The contract maintains a WASM hash, indicating deployment or interaction within a WebAssembly runtime environment.

Mermaid Diagram

flowchart TD
A[Constructor] --> B[AddJwkModulus]
A --> C[AddZKPfactor]
B --> D[DeleteJwkModulus]
C --> E[DeleteZKPfactor]
A --> F[AddSecurityCard]
F --> G[DeleteSecurityCard]
A --> H[SendTransaction]
H --> I[SubmitTransaction]
I --> J[ConfirmTransaction]
A --> K[UpdateRecoveryPhrase]
A --> L[UpdateSeedPhrase]
A --> M[GetTransaction]
M --> N[GetTransactions]
M --> O[GetTransactionIds]
A --> P[CleanAllExpiredJwks]
A --> Q[CleanAllExpiredZKPFactors]
A --> R[TurnOnSecurityCards]
R --> S[TurnOffSecurityCards]
A --> T[SetMinValue]
A --> U[SetMaxCleanupTxns]

This diagram represents the primary workflow and relationships between key functions facilitating multifactor authentication, key management, transaction processing, and security card operations within the contract.