Opaque Token

keccak256(abi.encode(salt, tokenId, value))

// where  salt (bytes32)    - random 32bytes to increase the entropy and
//                            make brute-forcing the hash impossible
//        tokenId (bytes32) - a unique tokenId within token's smart contract instance
//        value (uint256)   - the value of the position

interface OpaqueToken {
  //
  // TYPES
  //

  struct SIGNATURE {
    uint8 v; bytes32 r; bytes32 s;
  }

  struct ORACLECONFIG {
    uint8 minNumberOfOracles; // min. number of oracle signatures required for reorg
    address[] oracles;        // valid oracles
  }

  //
  // EVENTS
  //

  /**
   * @dev MUST be emitted when new token is created
   * @param initiatedBy address that created and controls the token
   * @param tokenId identifier of the token
   * @param totalSupplyBasket initial supply basket, containing total supply of tokens
   * @param ref custom reference as used by initiator
   */
  event CreateToken(address initiatedBy, bytes32 tokenId, bytes32 totalSupplyBasket, bytes32 ref);

  /**
   * @dev MUST be emitted on issuance
   * @param initiatedBy address that initiated issuance
   * @param baskets baskets that were issued to the receiver
   * @param receiver address that received baskets
   * @param ref custom reference as used by initiator
   */
  event Issue(address initiatedBy, bytes32[] baskets, address receiver, bytes32 ref);

  /**
   * @dev MUST be emitted when holder baskets are restructured
   * @param initiatedBy address that initiated reorg and owner of all baskets
   * @param basketsIn baskets that are restructured and no longer exist
   * @param basketsOut baskets that are newly created
   * @param ref custom reference as used by initiator
   */
  event ReorgHolderBaskets(address initiatedBy, bytes32[] basketsIn, bytes32[] basketsOut, bytes32 ref);

  /**
   * @dev MUST be emitted when supply baskets are restructured
   * @param initiatedBy address that initiated reorg
   * @param basketsIn supply baskets that are restructured and no longer exist
   * @param basketsOut supply baskets that are newly created
   * @param ref custom reference as used by initiator
   */
  event ReorgSupplyBaskets(address initiatedBy, bytes32[] basketsIn, bytes32[] basketsOut, bytes32 ref);

  /**
   * @dev MUST be emitted when baskets are transferred from one address to another
   * @param initiatedBy address that initiated the transfer
   * @param receiver address that is the new owner of baskets
   * @param baskets baskets that were transferred
   * @param ref custom reference as used by initiator
   */
  event Transfer(address initiatedBy, address receiver, bytes32[] baskets, bytes32 ref);

  /**
   * @dev MUST be emitted on redeem
   * @param initiatedBy address that initiated redeem
   * @param baskets baskets that were redeemed
   * @param ref custom reference as used by initiator
   */
  event Redeem(address initiatedBy, bytes32[] baskets, bytes32 ref);

  //
  // FUNCTIONS
  //

  /**
   * @dev returns the configuration for this token
   */
  function oracleConfig() external view returns (ORACLECONFIG memory);

  /**
   * @dev returns the address of the basket owner
   */
  function owner(bytes32 basket) external view returns (address);

  /**
   * @dev returns the total supply for a `tokenId``
   * All token investors are allowed to fetch this value from the token operator's off-chain storage.
   */
  function totalSupply(bytes32 tokenId) external view returns (bytes32);

  /**
   * @dev returns the operator of this token, who is also responsible for providing the main
   * off-chain storage source.
   */
  function operator() external view returns (address);
  
  /**
   * @dev Allows the token operator to create a new token with the specified `tokenId` and an initial 
   * `totalSupplyBasket`. The `totalSupplyBasket` can be partitioned using {reorgSupplyBaskets} as needed 
   * when calling {issue}. The `ref` parameter can be used freely by the caller for any reference purpose.
   */
  function createToken(
      bytes32 tokenId,
      bytes32 totalSupplyBasket,
      bytes32 ref
  ) external;

  /**
   * @dev Allows the token operator to issue tokens by assigning `supplyBaskets` to a `receiver` which 
   * becomes the owner of these baskets. 
   */
  function issue(
      bytes32[] calldata supplyBaskets,
      address receiver,
      bytes32 ref
  ) external;
  
  /**
   * @dev transfers `baskets` to a `receiver` who becomes the new owner of these baskets. 
   */
  function transfer(
      bytes32[] calldata baskets,
      address receiver,
      bytes32 ref
  ) external;

  /**
   * @dev reorganizes a set of holder baskets (`basketsIn`) to a new set (`basketsOut`) having
   * the same value, i.e., the sum of all values from input baskets equals the sum of values
   * in output baskets. In order to ensure the integrity, external oracle service is required that
   * will sign the reorg proposal requested by the basket owner, which is passed as `reorgOracleSignatures`.
   * The minimum number of oracle signatures is defined in the oracle configuration.
   */
  function reorgHolderBaskets(
      SIGNATURE[] calldata reorgOracleSignatures,
      bytes32[] calldata basketsIn,
      bytes32[] calldata basketsOut,
      bytes32 ref
  ) external;

  /**
   * @dev same as {reorgHolderBaskets}, but for the available supply baskets.
   */
  function reorgSupplyBaskets(
      SIGNATURE[] calldata reorgOracleSignatures,
      bytes32[] calldata basketsIn,
      bytes32[] calldata basketsOut,
      bytes32 ref
  ) external;

  /**
   * @dev redeems holder's `baskets` and returns them to available supply
   */
  function redeem(
      bytes32[] calldata baskets,
      bytes32 ref
  ) external;

}

  Endpoint: PUT baskets
  Description: will store baskets if the `basket` hash is matching `data`.
  PostData: 
  [
    {
      basket: keccak256(abi.encode(salt, tokenId, value)),
      data: {
        salt: <bytes32>,
        tokenId: <bytes32>,
        value: <uint256>
      }
    },
    ...
  ]

  Endpoint: GET baskets?basket-hash=<bytes32>
  Description: will return the list of baskets depending on the query parameters.
  Query Parameters:
    - basket-hash (optional): returns one basket matching the requested hash
    - if no query parameter is set, then the endpoint will return all baskets of the requestor
  Response:
  [
    {
      basket: keccak256(abi.encode(salt, tokenId, value)),
      data: {
        salt: <bytes32>,
        tokenId: <bytes32>,
        value: <uint256>
      }
    },
    ...
  ]

Endpoint: POST reorg
PostData:
{
  in: [
    {
      basket: keccak256(abi.encode(salt, tokenId, value)),
      data: {
        salt: <bytes32>,
        tokenId: <bytes32>,
        value: <uint256>
      }
    },
    ...
  ],
  out: [
    {
      basket: keccak256(abi.encode(salt, tokenId, value)),
      data: {
        salt: <bytes32>,
        tokenId: <bytes32>,
        value: <uint256>
      }
    },
    ...
  ]
}

Response: {
    // hash is signed with oracles private key
    // basketsIn and basketsIn are bytes32[]
    signature: sign(keccak256(abi.encode(basketsIn, basketsOut)))
}

in : (..., token1, 10), (..., token1, 30), (..., token2, 5), (..., token2, 95)
out: (..., token1, 40), (..., token2, 100)

in : (..., token1, 40), (..., token2, 100)
out: (..., token1, 10), (..., token1, 30), (..., token2, 5), (..., token2, 95)

A owns basket-a1{..., value:10}
B owns basket-b1{..., value:5}, basket-b2{..., value:15}, ...
A: transfer basket-a1 to B
B: reorg [basket-a1, basket-b1, basket-b2]
      to [basket-b3{..., value:10}, basket-b4{..., value:10}, basket-b5:{..., value:10},
            basket-b6:{..., value:0}, basket-b7:{..., value:0}]
      where sum of inputs is the sum of outputs
B: transfer basket-b5{value:10} to C
B: transfer basket-b6{value:0}  to D
B: transfer basket-b7{value:0}  to E