Mvmultifactor.abi.json
Overview
This file defines the Application Binary Interface (ABI) for a smart contract responsible for managing multifactor authentication and cryptographic key management on a blockchain platform. It specifies the contract's version, initialization parameters, state variables (fields), and a comprehensive set of functions that handle creation, update, removal, and querying of multifactor authentication factors, cryptographic keys, security cards, transactions, and recovery mechanisms.
The contract enables a multifactor cryptographic identity management system by controlling ephemeral public keys, JSON Web Key (JWK) moduli, zero-knowledge proof (ZKP) factors, security cards, and a transaction submission and confirmation mechanism with various safeguards such as whitelists and expiration timestamps.
Key Functional Areas
Initialization and Setup: Constructor function initializes identity parameters including zkID, proof artifacts, JWK moduli, provider certificates, recovery keys, and indexes.
Whitelist Management: Functions to set, update, and clean whitelists controlling allowed addresses or factors.
JWK Modulus Management: Adding, deleting, and cleaning JWK moduli with expiration control.
ZKP Factor Management: Adding, deleting, and cleaning zero-knowledge proof factors, with expiration and signature verification.
Security Card Management: Adding, deleting, enabling, and disabling security cards as an additional security layer.
Transaction Management: Submitting, confirming, and querying transactions, including transaction cleanup controls.
Recovery and Seed Phrase Management: Updating recovery keys, seed phrases, and handling candidate seed phrases with expiration.
Version and Metadata Accessors: Functions to retrieve contract version, timestamps, public keys, and other metadata.
Detailed Function Descriptions
constructor
Purpose: Initializes the contract with all necessary identity and security parameters.
Parameters:
name (string): Human-readable name for the identity.
zkid(string): Zero-knowledge identifier string.proof(bytes): Cryptographic proof bytes.epk(uint256): Ephemeral public key.epk_sig(bytes): Signature for the ephemeral public key.epk_expire_at(uint64): Expiration timestamp for theepk.jwk_modulus (bytes): JSON Web Key modulus bytes.
kid(bytes): Key ID associated with the JWK.jwk_modulus_expire_at (uint64): Expiration timestamp for the JWK modulus.
index_mod_4 (uint8): Index modulo 4, a routing or indexing parameter.
iss_base_64(string): Base64 encoded issuer string.provider(string): Provider identifier string.header_base_64(string): Base64 encoded header.pub_recovery_key(uint256): Public recovery key.pub_recovery_key_sig(bytes): Signature of the recovery key.jwk_update_key (uint256): Key used to update JWK keys.
jwk_update_key_sig (bytes): Signature of the JWK update key.
root_provider_certificates(map(uint256, bytes)): Map of root provider certificates indexed by serial number.index(uint128): Index identifier, possibly for sharding or mapping.
Returns: None.
Usage Example:
contract.constructor(
"Alice",
"zkid-string",
proofBytes,
ephemeralPubKey,
ephemeralPubKeySig,
epkExpireTimestamp,
jwkModulusBytes,
kidBytes,
jwkModulusExpireAt,
2,
"issuerBase64",
"providerName",
"headerBase64",
pubRecoveryKey,
pubRecoveryKeySig,
jwkUpdateKey,
jwkUpdateKeySig,
rootProviderCertMap,
indexValue
);
cleanWhiteList
Purpose: Removes entries from the whitelist based on expiration timestamp.
Parameters:
epk_expire_at(uint32): Timestamp to clean whitelist entries expiring before this time.
Returns: None.
updateWhiteList
Purpose: Updates the whitelist entry for a specific index and name.
Parameters:
epk_expire_at(uint32): Expiration timestamp for ephemeral public keys.index(uint8): Index for the whitelist entry.name (string): Name associated with the whitelist entry.
indexMirror (uint128): Mirror index for referencing.
Returns: None.
setWhiteList
Purpose: Sets or replaces whitelist entry for a given address and index.
Parameters:
new_addr(address): Address to whitelist.index(uint128): Index position for the whitelist entry.
Returns: None.
addJwkModulus
Purpose: Adds a new JWK modulus entry validated by a root certificate.
Parameters:
root_cert_sn(uint256): Serial number of the root certificate.lv_kid(bytes): Level key ID.tls_data (bytes): TLS data associated with the key.
Returns:
success (bool): Indicates if the addition was successful.
deleteJwkModulusByUpdateJwkKey
Purpose: Deletes a JWK modulus entry authorized by the update JWK key.
Parameters:
kid(bytes): Key ID of the JWK modulus to delete.
Returns: None.
cleanAllExpiredJwks
Purpose: Cleans all expired JWK modulus entries based on expiration timestamp.
Parameters:
epk_expire_at(uint64): Expiration cutoff timestamp.
Returns: None.
addZKPfactor
Purpose: Adds a zero-knowledge proof factor.
Parameters:
proof(bytes): Proof bytes for the factor.epk(uint256): Ephemeral public key.kid(bytes): Key ID related to the factor.header_base_64(string): Base64 encoded header.epk_expire_at(uint64): Expiration timestamp for the ephemeral public key.
Returns:
success (bool): Indicates if the addition succeeded.
deleteZKPfactorByItself
Purpose: Deletes a ZKP factor by its expiration timestamp.
Parameters:
epk_expire_at(uint64): Expiration timestamp.
Returns: None.
cleanAllExpiredZKPFactors
Purpose: Cleans all expired zero-knowledge proof factors.
Parameters:
epk_expire_at(uint64): Expiration cutoff timestamp.
Returns: None.
setWasmHash
Purpose: Sets the WebAssembly (WASM) hash for the contract, possibly for code verification.
Parameters:
wasm_hash (bytes): Hash value bytes.
Returns: None.
setForceRemoveOldest
Purpose: Enables or disables automatic removal of the oldest entries.
Parameters:
flag (bool): True to force removal, false otherwise.
Returns: None.
addRootProviderCertificate
Purpose: Adds a new root provider certificate.
Parameters:
sn (uint256): Serial number of the certificate.
root_provider_certificate(bytes): Certificate bytes.
Returns: None.
deleteRootProviderCertificate
Purpose: Deletes a root provider certificate by serial number.
Parameters:
sn (uint256): Serial number of the certificate.
Returns: None.
cleanRootProviderCertificates
Purpose: Cleans all root provider certificates.
Parameters: None.
Returns: None.
cleanAllJwks
Purpose: Cleans all JWK modulus entries regardless of expiration.
Parameters: None.
Returns: None.
cleanAllZKPFactors
Purpose: Cleans all zero-knowledge proof factors.
Parameters: None.
Returns: None.
updateRecoveryPhrase
Purpose: Updates the public recovery key and its signature.
Parameters:
new_pub_recovery_key(uint256): New recovery public key.new_pub_recovery_key_sig(bytes): Signature of the new recovery key.
Returns: None.
updateJwkUpdateKey
Purpose: Updates the JWK update key and its signature.
Parameters:
new_jwk_update_key (uint256): New JWK update key.
new_jwk_update_key_sig (bytes): Signature of the new JWK update key.
Returns: None.
updateZkid
Purpose: Updates the zero-knowledge ID and related parameters.
Parameters:
zkid(string): New zero-knowledge ID.proof(bytes): Proof bytes.epk(uint256): Ephemeral public key.epk_sig(bytes): Signature of the ephemeral public key.kid(bytes): Key ID.jwk_modulus (bytes): JWK modulus bytes.
jwk_modulus_expire_at (uint64): Expiration timestamp.
index_mod_4 (uint8): Index modulo 4.
iss_base_64(string): Base64 encoded issuer string.header_base_64(string): Base64 encoded header.epk_expire_at(uint64): Expiration timestamp.jwk_update_key (uint256): JWK update key.
jwk_update_key_sig (bytes): Signature of the JWK update key.
provider(string): Provider string.root_provider_certificates(map(uint256,bytes)): Root certificates map.
Returns: None.
updateSeedPhrase
Purpose: Updates the owner's public key and its signature for seed phrase recovery.
Parameters:
new_owner_pubkey (uint256): New owner public key.
new_owner_pubkey_sig (bytes): Signature of the new owner public key.
Returns: None.
deleteJwkModulus
Purpose: Deletes a JWK modulus by key ID.
Parameters:
kid(bytes): Key ID to delete.
Returns: None.
deleteZKPfactor
Purpose: Deletes a zero-knowledge proof factor by expiration and ephemeral public key.
Parameters:
epk_expire_at(uint64): Expiration timestamp.epk(uint256): Ephemeral public key.
Returns: None.
deleteZKPfactor_
Purpose: Deletes a zero-knowledge proof factor by ephemeral public key only.
Parameters:
epk(uint256): Ephemeral public key.
Returns: None.
changeSeedPhrase
Purpose: Initiates a change of seed phrase with expiration and signatures.
Parameters:
epk_expire_at(uint64): Expiration timestamp.new_owner_pubkey (uint256): New owner public key.
new_owner_pubkey_sig (bytes): Signature of the new owner public key.
Returns: None.
acceptCandidateSeedPhrase
Purpose: Accepts a candidate seed phrase to finalize the seed phrase change.
Parameters:
new_owner_pubkey (uint256): New owner public key.
Returns: None.
deleteCandidateSeedPhrase
Purpose: Deletes a candidate seed phrase based on expiration timestamp.
Parameters:
epk_expire_at(uint64): Expiration timestamp.
Returns: None.
addSecurityCard
Purpose: Adds a security card public key with its signature.
Parameters:
pubkey (uint256): Public key of the security card.
pubkey_sig(bytes): Signature of the public key.
Returns: None.
turnOffSecurityCards
Purpose: Disables the use of all security cards.
Parameters: None.
Returns: None.
turnOnSecurityCards
Purpose: Enables the use of security cards.
Parameters: None.
Returns: None.
deleteSecurityCard
Purpose: Deletes a security card by public key.
Parameters:
pubkey (uint256): Public key of the security card.
Returns: None.
deleteAllSecurityCards
Purpose: Deletes all registered security cards.
Parameters: None.
Returns: None.
sendTransaction
Purpose: Sends a transaction from the contract with specified parameters.
Parameters:
epk_expire_at(uint64): Expiration timestamp for ephemeral key validation.dest (address): Destination address for the transaction.
value (uint128): Amount to send.
cc (map(uint32,varuint32)): Custom code or call data map.
bounce(bool): Bounce flag for transaction.flags(uint8): Send flags.payload(cell): Payload cell.
Returns:
value0(address): Address related to the transaction.
submitTransaction
Purpose: Submits a transaction and returns a transaction ID.
Parameters:
epk_expire_at(uint64): Expiration timestamp.dest (address): Destination address.
value (uint128): Value to send.
cc (map(uint32,varuint32)): Custom call data map.
bounce(bool): Bounce flag.allBalance(bool): Flag indicating whether to send all balance.payload(cell): Payload data.
Returns:
transId(uint64): Transaction identifier.
confirmTransaction
Purpose: Confirms a transaction by its ID.
Parameters:
transactionId (uint64): Transaction ID.
Returns: None.
setMaxCleanupTxns
Purpose: Sets the maximum number of transactions to clean up.
Parameters:
epk_expire_at(uint64): Expiration timestamp.value (uint256): Maximum cleanup transactions count.
Returns: None.
setMinValue
Purpose: Sets the minimum value for transactions.
Parameters:
epk_expire_at(uint64): Expiration timestamp.value (uint128): Minimum value.
Returns: None.
getTransaction
Purpose: Retrieves details of a specific transaction.
Parameters:
transactionId (uint64): Transaction ID.
Returns:
trans (tuple): Transaction details including
id,creator, dest, value, cc, sendFlags,payload, andbounce.
getTransactions
Purpose: Retrieves all transactions stored in the contract.
Parameters: None.
Returns:
transactions (tuple[]): Array of transaction tuples.
getTransactionIds
Purpose: Retrieves the list of all transaction IDs.
Parameters: None.
Returns:
ids(uint64[]): Array of transaction IDs.
getZKPEphemeralPublicKeys
Purpose: Retrieves all ephemeral public keys used in zero-knowledge proofs.
Parameters: None.
Returns:
value0(uint256[]): Array of ephemeral public keys.
getTimeStamp
Purpose: Retrieves the current contract timestamp.
Parameters: None.
Returns:
value0(uint32): Current timestamp.
getSecurityCardKeys
Purpose: Retrieves all registered security card public keys.
Parameters: None.
Returns:
sc_keys(uint256[]): Array of security card keys.
get_epk_expire_at
Purpose: Retrieves expiration timestamp for a given ephemeral public key.
Parameters:
epk(uint256): Ephemeral public key.
Returns:
value0(uint64): Expiration timestamp.
getVersion
Purpose: Retrieves the contract version information.
Parameters: None.
Returns:
value0(string): ABI version.value1(string): Contract version.
Accessor Functions
Functions beginning with underscore (_) provide read access to internal state variables including:
_factors_ordered_by_timestamp: Map of factors indexed by timestamp.
_factors_len: Number of factors._name: Identity name.
_pub_recovery_key: Public recovery key._jwk_update_key: JWK update key.
_root_provider_certificates: Map of root provider certificates.
_jwk_modulus_data: Map of JWK modulus data and expiration.
_jwk_modulus_data_len: Number of JWK modulus entries.
_zkid: Zero-knowledge ID._index_mod_4: Index modulo 4.
_iss_base_64: Issuer string in base64._lv_provider_bytes: Provider bytes._use_security_card: Boolean flag if security cards are used._m_security_cards: Map of security cards._m_security_cards_len: Number of security cards._m_transactions: Map of transactions.
_m_transactions_len: Number of transactions.
_min_value: Minimum transaction value._max_cleanup_txns: Maximum cleanup transactions.
_force_remove_oldest: Flag for forced removal of oldest entries._verification_key_index: Verification key index._wasm_hash: WASM hash bytes.
Important Implementation Details and Algorithms
Expiration-Based Cleanup: Several functions use expiration timestamps (
epk_expire_at) to remove outdated keys or factors, ensuring the contract maintains current and valid authentication factors.Signature Verification: Functions managing keys and recovery mechanisms require associated signatures (
epk_sig,pub_recovery_key_sig, etc.) to validate authenticity and prevent unauthorized modifications.Mapping Structures: Uses maps extensively for storage of keys, certificates, transactions, and security cards, enabling efficient lookups and management.
Transaction Lifecycle: Transactions go through a lifecycle of submission (submitTransaction), confirmation (confirmTransaction), and retrieval (getTransaction(s)), supporting multi-factor confirmation workflows.
Security Cards Management: Security cards serve as an additional factor, with enable/disable functionality to strengthen or relax security policies dynamically.
Modular Key Updates: Supports updating JWK moduli separately via authorized keys, enabling cryptographic agility.
Interaction with Other System Components
Root Provider Certificates: These certificates, stored as maps, likely interact with external certificate authorities or providers for trust verification.
Security Cards: Interaction with physical or virtual security cards for multifactor authentication.
Transactions: Interacts with the blockchain's transaction processing system, submitting and confirming transactions.
**Zero-Knowledge