Social Media Contract

Imagine a social media smart contract which passes storage costs onto users for posts and follower data. Let's say this this contract is deployed at account social. Like the Fungible Token contract example above, the storage_balance_bounds.min is 0.00235, because this contract will likewise add a newly-registered user to an internal Map. However, this contract sets no storage_balance_bounds.max, since users can add more data to the contract over time and must cover the cost for this storage.

So for this contract, storage_balance_bounds will return:

{
  "min": "2350000000000000000000",
  "max": null
}

Let's follow a user, Alice with account alice, as she interacts with social through the following scenarios:

1. Registration
2. Unnecessary attempt to re-register using registration_only param
3. Attempting to take action which exceeds paid-for storage; increasing storage deposit
4. Removing storage and reclaiming excess deposit

1. Account registers with social

High-level explanation

Alice issues a transaction to deposit Ⓝ for her account. While the storage_balance_bounds.min for this contract is 0.00235Ⓝ, the frontend she uses suggests adding 0.1Ⓝ, so that she can immediately start adding data to the app, rather than only registering.

Technical calls

Using NEAR CLI:

near call social storage_deposit '' \
  --accountId alice --amount 0.1

The result:

{
  total: '100000000000000000000000',
  available: '97650000000000000000000'
}

Here we see that she has deposited 0.1Ⓝ and that 0.00235 of it has been used to register her account, and is therefore locked by the contract. The rest is available to facilitate interaction with the contract, but could also be withdrawn by Alice by using storage_withdraw.

2. Unnecessary attempt to re-register using registration_only param

High-level explanation

Alice can't remember if she already registered and re-sends the call, using the registration_only param to ensure she doesn't attach another 0.1Ⓝ.

Technical calls

Using NEAR CLI:

near call social storage_deposit '{"registration_only": true}' \
  --accountId alice --amount 0.1

The result:

{
  total: '100000000000000000000000',
  available: '97650000000000000000000'
}

Additionally, Alice will be refunded the extra 0.1Ⓝ that she just attached. This makes it easy for other contracts to always attempt to register users while performing batch transactions without worrying about errors or lost deposits.

Note that if Alice had not included registration_only, she would have ended up with a total of 0.2Ⓝ.

3. Account increases storage deposit

Assumption: social has a post function which allows creating a new post with free-form text. Alice has used almost all of her available storage balance. She attempts to call post with a large amount of text, and the transaction aborts because she needs to pay for more storage first.

Note that applications will probably want to avoid this situation in the first place by prompting users to top up storage deposits sufficiently before available balance runs out.

High-level explanation

1. Alice issues a transaction, let's say social.post, and it fails with an intelligible error message to tell her that she has an insufficient storage balance to cover the cost of the operation
2. Alice issues a transaction to increase her storage balance
3. Alice retries the initial transaction and it succeeds

Technical calls

1. This is outside the scope of this spec, but let's say Alice calls near call social post '{ "text": "very long message" }', and that this fails with a message saying something like "Insufficient storage deposit for transaction. Please call storage_deposit and attach at least 0.1 NEAR, then try again."

2. Alice deposits the proper amount in a transaction by calling social::storage_deposit with the attached deposit of '0.1'. Using NEAR CLI:

   near call social storage_deposit ''
   --accountId alice --amount 0.1

The result:

{
  total: '200000000000000000000000',
  available: '100100000000000000000000'
}

3. Alice tries the initial near call social post call again. It works.

4. Removing storage and reclaiming excess deposit

Assumption: Alice has more deposited than she is using.

High-level explanation

1. Alice views her storage balance and sees that she has extra.
2. Alice withdraws her excess deposit.

Technical calls

1. Alice queries social::storage_balance_of({ "account_id": "alice" }).

With NEAR CLI:

near view social storage_balance_of '{"account_id": "alice"}'

Response:

{
  total: '200000000000000000000000',
  available: '100100000000000000000000'
}

2. Alice calls storage_withdraw with a 1 yoctoⓃ deposit. NEAR CLI command:

   near call social storage_withdraw
   '{"amount": "100100000000000000000000"}'
   --accountId alice --depositYocto 1

Result:

{
  total: '200000000000000000000000',
  available: '0'
}