Update documentation for 2.0 release

[ailisp]

We have a couple of new features and some breaking changes since 1.0 release, this ticket is about checking every markdown documentation in the repo and docs.near.org.

[fospring]

prerelease version: near-sdk-js@2.0.0-0,diff from v1.0.0

Features

@ailisp @gagdiez here are some features to be added in the 2.0 prerelease version, pls review it. And I will create a 2.0 release version after you have reviewed it.

1. borsh data de/serializer for contract state

• use for: new contracts or migrate from a borsh serialized contract
  example: https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message-borsh.js
  this case can be added in here: https://docs.near.org/build/smart-contracts/release/upgrade#example-guest-book-migration

@NearBindgen({
    serializer(statusMessage) {
        return borsh.serialize(schema, statusMessage);
    },
    deserializer(value) {
        return borsh.deserialize(schema, value);
    }
})
export class StatusMessage {
    constructor() {
        this.records = new Map()
    }

    @call({})
    set_status({ message }) {
        let account_id = near.signerAccountId()
        env.log(`${account_id} set_status with message ${message}`)
        this.records.set(account_id, message)
    }

    @view({})
    get_status({ account_id }) {
        env.log(`get_status for account_id ${account_id}`)
        return this.records.get(account_id) || null
    }
}

2. js contract migration with data fields

example: https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message-migrate-add-field.js
this case can be update in here: https://docs.near.org/build/smart-contracts/release/upgrade#example-guest-book-migration

import {NearBindgen, call, view, near, migrate, Vector, assert} from "near-sdk-js";

class OldStatusMessage {
  constructor() {
    this.records = {};
  }
}

@NearBindgen({})
export class StatusMessage {
  constructor() {
    this.records = {};
    this.new_fields = {}; // new added filed
  }
  ...

  // Migrate from OldStatusMessage to StatusMessage
  @migrate({})
  migrateState() {
    assert(this.records !== undefined, "Contract state should not be deserialized in @migrate");
    // retrieve the current state from the contract
    let records = JSON.parse(near.storageRead("STATE")).records;

    this.records = records;
    this.new_fields = {};
  }
}

3. auto reconstruct class from object by static json schema

• use for contract serialzed by default method(json), the document is here: https://github.com/near/near-sdk-js/blob/develop/AUTO_RECONSCTRUCT_BY_JSON_SCHEME.md#the-schema-format

and the example is here: https://github.com/near/near-sdk-js/blob/develop/examples/src/status-deserialize-class.js#L49

class Car {
    static schema = {
        name: "string",
        speed: "number",
    };
    constructor() {
        this.name = "";
        this.speed = 0;
    }

    info() {
        return this.name + " run with speed " + this.speed.toString()
    }
}

class Truck {
    static schema = {
        name: "string",
        speed: "number",
        loads: UnorderedMap
    };
    constructor() {
        this.name = "";
        this.speed = 0;
        this.loads = new UnorderedMap("tra");
    }

    info() {
        return this.name + " run with speed " + this.speed.toString() + " with loads length: " + this.loads.toArray().length;
    }
}

// sdk should first try if UnorderedMap has a static schema and use it to recursively decode.
@NearBindgen({})
export class StatusDeserializeClass {
    static schema = {
        truck: Truck,
        efficient_recordes: UnorderedMap,
        nested_efficient_recordes: {class: UnorderedMap, value: UnorderedMap},
        nested_lookup_recordes:  {class: UnorderedMap, value: LookupMap},
        vector_nested_group: {class: Vector, value: LookupMap},
        lookup_nest_vec: { class: LookupMap, value: Vector },
        unordered_set: UnorderedSet,
        user_car_map: {class: UnorderedMap, value: Car },
        big_num: 'bigint',
        date: 'date'
    };
    constructor() {
        this.is_inited = false;
        this.records = {};
        this.truck = new Truck();
        this.messages = [];
        this.efficient_recordes = new UnorderedMap("a");
        this.nested_efficient_recordes = new UnorderedMap("b");
        this.nested_lookup_recordes = new UnorderedMap("c");
        this.vector_nested_group = new Vector("d");
        this.lookup_nest_vec = new LookupMap("e");
        this.unordered_set = new UnorderedSet("f");
        this.user_car_map = new UnorderedMap("g");
        this.big_num = 1n;
        this.date = new Date();
        this.message_without_schema_defined = "";
        this.number_without_schema_defined = 0;
        this.records_without_schema_defined = {};
    }
    ...
}

4. query data Nesting of objects in SDK Collections without reconstructor

• use for SDK Collections which has description in static json schema
• example: https://github.com/near/near-sdk-js/blob/develop/examples/src/status-deserialize-class.js#L231
• example cound be update in this page's Nesting of Objects - Temporary Solution module: https://docs.near.org/build/smart-contracts/anatomy/storage#map

// sdk should first try if UnorderedMap has a static schema and use it to recursively decode.
@NearBindgen({})
export class StatusDeserializeClass {
    static schema = {
        truck: Truck,
        efficient_recordes: UnorderedMap,
        nested_efficient_recordes: {class: UnorderedMap, value: UnorderedMap},
        nested_lookup_recordes:  {class: UnorderedMap, value: LookupMap},
        vector_nested_group: {class: Vector, value: LookupMap},
        lookup_nest_vec: { class: LookupMap, value: Vector },
        unordered_set: UnorderedSet,
        user_car_map: {class: UnorderedMap, value: Car },
        big_num: 'bigint',
        date: 'date'
    };
    constructor() {
        this.is_inited = false;
        this.records = {};
        this.truck = new Truck();
        this.messages = [];
        // account_id -> message
        this.efficient_recordes = new UnorderedMap("a");
        // id -> account_id -> message
        this.nested_efficient_recordes = new UnorderedMap("b");
        // id -> account_id -> message
        this.nested_lookup_recordes = new UnorderedMap("c");
        // index -> account_id -> message
        this.vector_nested_group = new Vector("d");
        // account_id -> index -> message
        this.lookup_nest_vec = new LookupMap("e");
        this.unordered_set = new UnorderedSet("f");
        this.user_car_map = new UnorderedMap("g");
        this.big_num = 1n;
        this.date = new Date();
        this.message_without_schema_defined = "";
        this.number_without_schema_defined = 0;
        this.records_without_schema_defined = {};
    }

    @call({})
    init_contract({ }) {
        if (this.is_inited) {
            near.log(`message inited`);
            return;
        }
        this.is_inited = true;
    }
    ...

    @call({})
    set_nested_efficient_recordes({ message, id }) {
        let account_id = near.signerAccountId();
        near.log(`${account_id} set_nested_efficient_recordes with message ${message},id ${id}`);
        this.efficient_recordes.set(account_id, message);
        const nestedMap = this.nested_efficient_recordes.get(id, {
            defaultValue: new UnorderedMap("i_" + id + "_"),
        });
        nestedMap.set(account_id, message);
        this.nested_efficient_recordes.set(id, nestedMap);

        const nestedLookup = this.nested_lookup_recordes.get(id, {
            defaultValue: new LookupMap("li_" + id + "_"),
        });
        nestedLookup.set(account_id, message);
        this.nested_lookup_recordes.set(id, nestedLookup);

        // vector_nested_group: {vector: {value: { lookup_map: {value: 'string'}}}},
        const vecNestedLookup = this.vector_nested_group.get(0, {
            defaultValue: new LookupMap("di_0_"),
        });
        vecNestedLookup.set(account_id, message);
        if (this.vector_nested_group.isEmpty()) {
            this.vector_nested_group.push(vecNestedLookup);
        } else {
            this.vector_nested_group.replace(0, vecNestedLookup);
        }

        const lookupNestVec = this.lookup_nest_vec.get(account_id, {
            defaultValue: new Vector("ei_" + account_id + "_"),
        });
        lookupNestVec.push(message);
        this.lookup_nest_vec.set(account_id, lookupNestVec);

        this.unordered_set.set(account_id);
    }

    @view({})
    get_nested_efficient_recordes({ account_id, id }) {
        near.log(`get_nested_efficient_recordes for account_id ${account_id}, id ${id}`);
        return this.nested_efficient_recordes.get(id, {
            defaultValue: new UnorderedMap("i_" + id + "_"),
        }).get(account_id);
    }

    @view({})
    get_nested_lookup_recordes({ account_id, id }) {
        near.log(`get_nested_lookup_recordes for account_id ${account_id}, id ${id}`);
        return this.nested_lookup_recordes.get(id, {
            defaultValue: new LookupMap("li_" + id + "_"),
        }).get(account_id);
    }

    @view({})
    get_vector_nested_group({ idx, account_id }) {
        near.log(`get_vector_nested_group for idx ${idx}, account_id ${account_id}`);
        return this.vector_nested_group.get(idx).get(account_id);
    }

    @view({})
    get_lookup_nested_vec({ account_id, idx }) {
        near.log(`get_looup_nested_vec for account_id ${account_id}, idx ${idx}`);
        return this.lookup_nest_vec.get(account_id).get(idx);
    }
    ...
}

Fixes

• WIP