Circular Wallet Architecture

Our first step is understanding that Circular wallets follow the CRC_0023 standard, defined in the CRC Standards Documentation. This standard encapsulates a wallet in a single file containing essential information, including the following key elements:

{
    "Version": "1.0.1",
    "Address": "02fc8b01bfc5dc291...",
    "PublicKey": "04da4a2f29cc41fe323...",
    "DateCreation": "2023:08:13-21:17:24",
    "Nonce": 3,
    "Assets": [
        {
            "Address": "",
            "Amount": 18077,
            "EnableSwap": 0,
            "Name": "Circular Coin",
            "Price": 1,
            "Royalties": 0,
            "Symbol": "CIRX",
            "Type": "C_TYPE_COIN",
            "URL": "",
            "URLType": ""
        },
        {
            "Address": "e2e86db8f44cea...",
            "Amount": 1,
            "Blockchain": "8a20baa40c45...",
            "EnableSwap": 0,
            "Name": "My NFT",
            "Price": 100,
            "Royalties": 0,
            "Symbol": "CBC",
            "Type": "CRC_NFT_0323",
            "URL": "https://....jpg",
            "URLType": "Digital Media"
        }
    ]
}

Unlike Ethereum, where wallet data is distributed as state variables in smart contracts, Circular centralizes wallet information in a single file for faster access. While it’s still possible to implement ERC-20-style contracts on Circular, where balances are stored within the contract, Circular instead stores user balances directly in wallets. This design choice significantly speeds up data retrieval by reducing the load on the virtual machine.

In systems where wallet data is scattered across smart contracts, managing millions of users can overwhelm the processing system, especially when dealing with large sets of wallet data. Circular solves this by storing wallet information in a single file, allowing it to quickly access and process relevant data through a native code routine. Typically, wallets contain a manageable number of tokens, so parsing through a small array of records is efficient and faster due to direct CPU processing. Once the necessary wallet data is extracted, the smart contract only processes the specific information it needs, reducing the overall data access time.

Circular also introduces a secondary Wallet Contract Data file, supporting the smart contract functionality while maintaining efficiency. This structure streamlines data processing, reduces system strain, and ensures fast, reliable access to wallet information. The CRC-0023 standard further enhances this architecture by integrating smart contract functionality into the wallet, adding a new layer of flexibility and utility.

The Wallet Contract Data (WCD) file acts as a centralized repository for each smart contract’s data, accessible through the contract’s address. Structured in JSON format, it provides a clear and organized view of contract information. Below is an example of a WCD record, demonstrating its format and how it efficiently organizes smart contract data:

Copy

{
    "ContractData": [
        {
            "Address": "b086dbfb88d66bf72d49c43ecca191d4bae4b126de40ce2c585fd3d6ece9986c",
            "Data": "7b2241646472657373223a2230786... CONTRACT DATA...22416c6c6f77616e636573223a7b7d7d"
        },
        {
            "Address": "2e6dab557a48d172bae899d18769263610403f707c23f67e6c415447e581726f",
            "Data": "7b2241646472657373223a2230786... CONTRACT DATA ...22416c6c6f77616e636573223a7b7d7d"
        },
        {
            "Address": "00088ac1e57012f89e37df6b01eaa9c196138a77a023ca4f8f5b8af38315b946",
            "Data": "7b2241646472657373223a2230786... CONTRACT DATA ...22416c6c6f77616e636573223a7b7d7d"
        }
    ]
}

Each smart contract in the system only accesses its own data, ensuring strong security and data integrity. The ‘Data’ field stores key information like balances and allowances. By limiting access to each contract’s designated data, the risk of misuse or fraud is minimized, creating a secure environment. Two system calls, Load and Save, manage wallet interactions, securely accessing and updating the data field.

/* Reads the wallet data */
function LoadWallet(walletaddres);

/* Stores the wallet data */
function SaveWallet(walletaddress, WalletData);

/* usage */

var W = LoadWallet("0x223424...");  // W  will contains the data read from the WCD

var Data = "...";

SaveWallet("0x3274629...", Data );

By integrating the LoadWallet and SaveWallet functions, we’ve established the foundation for smart contracts to read from and write to a CRC-0023 wallet. This gives contracts powerful capabilities, limited only by our creativity. However, it’s important to remember that each interaction with a wallet—whether reading or writing—is a permanent action that impacts all instances of that wallet across the entire network. For this reason, it’s crucial to act responsibly, limiting wallet interactions to only what is necessary to ensure your code remains efficient and performs optimally.