Tech guidebook

The Safex Big Box Store 101: An Introduction and Explanation

This article looks to give an in-depth overview of Big Box, the philosophy behind the All-In-One package concept, and the various components of the package that allow it to work.

SafeX

• 15 min read
The Safex Big Box Store 101: An Introduction and Explanation

The Safex Community has just seen the publication of the Safex Big Box Store Wallet.

This article looks to give an in-depth overview of Big Box, the philosophy behind the All-In-One package concept, and the various components of the package that allow it to work. Separate highly detailed walkthroughs on the installation, setup and use of Big Box can be found below (links will be live once the walkthroughs are published).

*The Lite Wallet version for Windows (which is just a one click installer) can be found here: https://github.com/safexninja/safex-big-box-store-wallet-lite/releases. A separate blog article will come out for the Lite wallet soon. Additionally, work is being progressed on a Mac version Lite Wallet.

This is the first in a series of articles, which looks to provide a complete set of tutorials regarding all aspects of the Big Box ecosystem. The articles in the series (including this one) are:

The 100-series articles contain entry-level information, designed for all users. The 200-series article is considered advanced-level, while the 300-series article is expert-level. Each walkthrough builds on the information provided in previous articles in the series.

The Safex Big Box Store Wallet allows users to buy and sell products on the Safex Marketplace.

The Big Box Store Wallet differs in fundamental concepts with the previously released TWM Safex wallet by Safex Market Inc. The TWM wallet is more of a “Lite” wallet, relying on remote connections with 3rd-party servers and nodes. In the words of the developer, it “is a community study on developing applications on top of the Safex blockchain and e-commerce protocol”.

The basic philosophy of the Big Box Store is a reduced reliance on external/remote wallet connections. This allows users to independently access the Safex Marketplace, thereby improving their online privacy, whilst also contributing to the decentralization of the Safex Blockchain.

However, the Safex Big Box Store Wallet runs on the Safex Blockchain, just like TWM Wallet and the older Orbiter wallet. Therefore, users who have old Safex wallet addresses from those other wallets can simply restore their old addresses into this wallet and after a hard rescan, all their balances, stakes and transaction history will appear. What won’t appear is any second layer data, such as messages relating to purchases made via the TWM Wallet.

The Big Box app includes the following “backend” software components, which all run locally on every user’s machine:

  • Safex Daemon
  • Mongodb (database)
  • Safex Block Explorer
  • Walletserver
  • API-Server
  • APP-server
  • Nginx

Let’s look at what each component does…

Safex Daemon

This is a Safex Node, running locally, which means that every Safex Big Box user becomes an integral part of the Safex blockchain itself. This achieves several things:

  1. Better privacy/data security for the user, as any transaction they create within the Big Box wallet is sent directly to their own node, rather than being sent to a remote Safex node run by someone else. Raw transaction data from the Big Box wallet doesn't leave your PC.
  2. Faster loading and response times for the application, because it loads all data from the local node instead of via some other centralized api on the other side of the world.
  3. Increases the decentralization of the Safex Blockchain, as every single Big Box user adds a Node to the Safex Blockchain and stores a copy of the blockchain ledger on their PC.

When the Safex Big Box app is first installed, it takes some time, due to syncing the entire Safex Blockchain prior to being able to use the Big Box app.  Subsequent use of the software only requires that the Node syncs back to the top block. With regular Big Box use, it only takes a few moments to complete synchronization to the current top block.

Mongodb (aka Database)

This is where all your private data gets stored, such as private keys for wallets and Merchant account keys. By keeping the data stored locally, you have the security of knowing you haven’t shared this critical information with a third party.

Your private information is secured using your Safex Big Box master password. Additionally, the following items are encrypted with a SHA-256 Hash of the master password:

  • Private keys for all wallets
  • Secret keys for all merchant accounts
  • Wallet file passwords
  • Contents of messages
  • Your default delivery address

What else is stored here?

  • User data
  • User settings
  • Wallet labels & balances
  • Merchant Account status
  • Connected storefront URLs with RSA keys, for communication per URL
  • Seller registrations and offers per storefront
  • Purchases, Orders, Messages (messages are stored locally once fetched from the storefront. When fetched successfully, the wallet makes a request to the storefront to delete the message, then the message is gone from the storefront.)
  • Transaction history
  • Error log

For those with the ability to read code, you can independently verify the file contents that defines the database structure:

https://github.com/safexninja/safex-big-box-store-wallet/blob/master/src/common/db/models/interfaces.ts

Safex Block Explorer

A standalone Safex Block Explorer negates the need for the Big Box app to rely on any remote third party block explorer. Included as part of the “self-sufficient user” philosophy of the Big Box Store. The Big Box Block Explorer accesses blockchain data directly from the local Safex Daemon.

Big Box Walletserver

Allows Safex Wallet functionality. This provides a server to handle wallet files, and keep connections open to the web based GUI. It is separated from the API-server and the APP-server to make sure the app keeps working if for some reason the wallet process crashes. Each wallet runs in its own process. Also, separating this from the other components is a preparation for making it scalable; working with wallets is very memory consuming. By making it a separate component it is possible to run multiple wallet-server instances on different servers with a load balancer, if anyone would want to run it in a business-like environment with multiple users.

Big Box API-Server

The API is basically the backend of the application. While the APP-server (see below) serves the GUI files to the browser, the API-server handles all user actions in the backend and does the heavy jobs.

The application that runs in the browser talks to this api-backend to handle and execute all user actions (create user, create wallet, purchase etc). This API-server can talk to the database (you cannot directly do it from the browser). Also, the API-server is the service that talks to the Store Front API’s to handle all those actions related to that store (show offer, hide offer, messaging).

For each Store Front you connect to, a RSA 4096 keypair and a messaging address is generated for the messaging part. (not for seller registration, show offer, hide offer).

Messages on the Store Front API awaiting collection by users.

When a seller registers their merchant account with a Store Front, it submits its message address and public key (pubkey) to the Store Front. When a buyer does a purchase, it fetches this message address and pubkey from the Store Front. Then the api creates a message and sends the buyers message address and pubkey to the seller, all encrypted with the sellers pubkey.

Then the seller receives the message, decrypts it with their private key, and gets the buyer's message address and pubkey from the message. Then communication between the two parties is set up. For each purchase the following information also gets sent (in encrypted form):

  • The delivery address
  • The quantity (which gets later verified from the txn)
  • The e-mail address if provided
  • The additional message if provided
  • Transaction proof of the purchase (later used by the seller to check whether you have proof of actually making the purchase transaction)

The API-server is scheduled to keep fetching messages every minute from Store Fronts for which:

  • You have an active seller registration
  • You have a purchase that is unclosed

Once you close a purchase or an order the communication between the two parties is automatically closed. It is also possible to close communication if the conversation is abused or for whatever reason (there is a button below the chat window).

Big Box APP-server

The APP-server is a HTTP(s) server which serves the front end files (javascript, html, css) to the browser. This is separated from the API-server (which is the backend) to enable easy replacement later on. It also allows the API to keep running when/if the front end crashes for whatever reason. It could have been 1 app together with the API-server, but for the reason of separating duties, it is not.

Nginx

Is used for web serving, which allows the Big Box app “frontend” to display and run in the user's preferred browser window.

---------------------------------------------

Using the Safex Big Box Store app

Having discussed the software components that support the Big Box Store, let’s now look at the startup processes to launch the software, and then interact with it.

Backend

The way you launch the backend will depend on the operating system being used, but regardless of the OS used, all versions of Big Box use a Docker container.

In simple terms, Docker is a platform that enables us to run applications in virtualized environments. Basically, it spins up multiple mini servers/services in a virtual machine. The benefit of this is that the application/code runs in an isolated environment (and not on your own OS) and, in that way, the application always runs under the same conditions, making it less error prone due to differences in operating systems. Although the use of Docker may not be commonly seen for simple household “end-user” applications, it is a widely used platform in larger IT-systems.

All of the above software components get launched in the “backend” terminal window using a single command.  The first time you launch the backend system, you get prompted to enter a master password - don’t forget this master password!

All the various components are downloaded, and the Safex Daemon/node syncs the blockchain. This process takes a variable amount of time, depending on your PC, internet speeds, and connection/s to other Safex nodes.

Afterwards, the blockchain syncs to the top block on each backend startup, you will see it run through various other startup processes, and eventually gives the following ASCII graphic in the terminal window.

Once you get presented with the above image in the backend terminal window, the software is fully launched and ready for use. You can now use your preferred web browser to access the frontend, as explained in detail shortly.

There’s also a built-in loader page that allows users to open their browser and see the processes being started in the backend and coming online. The exception to this is the initial install of docker and the first running of the backend processes - for this first instance, the user can only open the webpage once Docker finishes downloading all the stuff (blue lines in the terminal). On next runs, the user could open the page right after starting it and the loader page should be there immediately.

When you finish using the Safex Big Box Wallet, you simply close the web browser and then enter Control-C in the backend terminal window to gracefully stop all Big Box processes.

Frontend

When you launch the app in the browser window for the first time, you will need to create a Big Box user profile to login to the Safex Big Box ecosystem.

When first opened, the Safex Big Box Store opens directly into the Market page. On the left side of the screen is a navigation menu with the follow Buttons:

In addition to the above navigation pages, users will also be presented with the Messages & Management interface in both the Listings and Orders pages, when communicating via P2P message.

Wallet Buttons Explained

Wherever you are in the wallet, the button format used is consistent, and can be best explained with the following example for Sending SFX:

Let’s explore each of the pages…

Market

This is where users can go shopping for any products listed for sale in a Safex Big Box Store. Users simply “Enter the store” and the products listed for sale are displayed in the product catalog.

Note: All screen captures of the Big Box Store used in this article are of the testing “Stagenet” version. All addresses, coin balances and offers are fake and are for testing purposes only. The api.safex.ninja and gold.safex.ninja URLs are demonstration shops used for testing and cannot be accessed on the mainnet live version to buy real products.

Detailed information on this page is explored and explained in the Big Box 103: Shopper Walkthrough (Link).

Hot Tip 🔥

Click the seller’s name on any offer to filter the Market page to only show items offered by that seller.

Purchases

This is where users see purchases made with this Big Box username, along with accessing messages from the Merchant.

Detailed information on this page is explored and explained in Big Box 103: Shopper Walkthrough (see link in Market section, above)

Listings

Merchants wishing to sell items via a Safex Big Box Store use this page. The following functions are performed here:

  • Enter a Safex Big Box Store API URL
  • Select an active merchant account and either -
  • Create new product listings
  • Edit previous product listings
  • Request permission to list items for sale at the entered Big Box Store API, or
  • If already approved to sell, can Show (or Hide) products for sale in that Store.

Detailed information on this page is explored and explained in Big Box 201: Approved Merchant Walkthrough.

Orders

This is where merchants see orders received, along with accessing messages from the Shopper.

Detailed information on this page is explored and explained in Big Box 201: Approved Merchant Walkthrough (see link in Listings section, above)

Wallets

Users can create and restore multiple Safex Wallets here, and perform an assortment of functions relating to Safex Wallets, including Staking, Unstaking and the creation of Merchant Accounts.

For example, you can create a merchant wallet, a spending wallet, a mining wallet, a staking wallet, a savings wallet, an exchange wallet, etc., in order to keep a good overview of your different types of balances.

Detailed information on this page is explored and explained in Big Box 103: Core Safex Wallet Functions Walkthrough.

Logs

This page records any errors, warnings and other significant information events.

Settings

Allows you to preset your default Country and Shipping Address here, which auto-populates for any purchases you make.

All Active Store Front Merchant Account Registrations are also displayed here.

Messages & Management Interface

This interface is used in both the Purchases and Orders pages, and is how both shoppers and merchants communicate with each other, and progress the delivery status of a purchased item.

Messaging is done using a generated message address, with a different one for each Store Front url. Basically, the buyer's side has the set Store Front message address and an RSA keypair generated for every purchase. This ensures that no seller can ever link a buyer to any other messages/orders.

Any time a user has an unread message, the corresponding (normally white) Purchases and/or Orders menu heading changes to red. Within those pages, the purchase or order which has a new message displays the word New in red text beside the button that opens the Messages and Management Interface for that item.

Within each interface window, users can see the item that was bought, the offerID, the Big Box Store it was purchased through, along with the quantity, SFX price, and date/time of purchase.

Merchants can mark an order as Shipped by clicking the appropriate message in the interface.

If there are any issues with the goods upon arrival, the shopper can use the message system to contact the seller and discuss the issue, with a view to resolving the matter.

Shoppers can mark an order as Delivered by clicking the relevant message displayed to them, once the merchant has already set the item as Shipped.

Once the item has been shown as Delivered, either the buyer or merchant can close the communication window, which effectively puts the message instance ‘to bed’ in the Closed section of the workflow (in the Purchases page of the buyer and the Orders page of the Merchant). Once an interface is closed, no further messages can be sent in that instance.

When marked as Closed, they no longer display on the Purchases/Orders pages, unless the Load button is clicked, which then displays all closed messages and allows the user to go back into the interface (but it remains closed to any further chat).

The Big Box Store Front API

In Market, above, it has already been explained that to access products for sale, shoppers need to “Enter the Store”, so to speak, by typing in the URL of the relevant Big Box Store Front API they wish to shop in. From a buyers perspective, the only external component to the Big Box suite is the connection to the Big Box Store Front API, which dictates what products are shown in each shopper's Market page. It’s like stepping into a virtual shopping mall.

The Big Box Store Front API also allows the person/business operating the API to curate other merchants wanting to sell their products in their Store. It is the responsibility of the Big Box Store API operator to vet and manage who they approve to sell via their Store API, to ensure a clean, trustworthy, and enjoyable marketplace experience.

Note: All screen captures of the Big Box Store used in this article are of the testing “Stagenet” version. All addresses, coin balances and offers are fake and are for testing purposes only. The api.safex.ninja URL is a demonstration shop used for testing and cannot be accessed on the mainnet live version to buy real products.

It is anticipated that the Big Box Store Front API code will be publicly released in the very near future, allowing any merchant to set up and run their own custom Big Box Store API. They may choose to keep their Store Front API closed to other merchants, or they could approve others to sell items via their API. In this way, specialty shops or virtual shopping malls could be created, which focus on certain product categories.

An example of where the Big Box Store Front API could be used as a standalone Safex marketplace is where a large retailer wants to create an exclusive Big Box store for their customers. Such an example could be a large auto parts retailer that has thousands of products in their range. Rather than allow other merchants to sell in their store, they could choose to simply replicate their existing product lines onto their “Big Box Automotive Store”, and then promote their exclusive Store API URL on their website, and to their email subscribers.

An example of where the Big Box Store Front API could be used as a specialized shopping mall is, perhaps, a merchant selling precious metals (bullion and coins) could create a Store Front API for goods they sell exclusively in Europe. But they might invite other merchants who sell to a different customer base to use their Store API. So while the Store Front API owner covers Europe, then they may wish to accept another merchant who sells to North American customers, another who ships to Australia, and others who sell elsewhere in the world. In this way, their “Big Box Precious Metals Store” could become a global one-stop-shop for anyone, anywhere, looking to buy precious metals, with each merchant covering a different geographic region.

In such an example, all merchants selling via that particular Big Box Store API would be promoting the same URL to their existing customer bases.

Customers interested in buying precious metals would simply enter that particular Store Front API URL into the Store field on the Market page of the Big Box wallet to browse the various precious metals offered for sale. If they have preset their country in the Settings page, the products shown will be automatically filtered to only those products that ship to their country (or they can manually select the country from the dropdown, if they choose not to update their Settings page, or perhaps want to buy something for a friend or family member who lives elsewhere in the world).

A merchant may choose to register on multiple Big Box Store Front APIs, and have their products listed in various stores. As orders come in, the message box for that purchase displays the store in which the purchase was made.  A future version of the Big Box wallet could also include statistical sales information, to assist merchants in evaluating their sales performance for each Store Front they use.

Final Thoughts

The above information has been provided to educate new users on the fundamentals of the Big Box Store Wallet ecosystem. You can now move onto the next article in the series, Big Box 102: Installation & Setup Walkthrough, which takes you through the initial installation and setup process, and basic Safex wallet functions, of the Big Box ecosystem.

If users still have further questions, they should use the Safex Forum thread found here.

Likewise, if a user detects a bug, or perhaps has an idea to improve the store/wallet functionality, they can also use the above Forum link to make contact.

Sign up for more like this.

Enter your email
Subscribe