Securities and Permissioned Tokens

algob project:
├── assets
│   ├── asa.yaml
│   ├── clawback.py
│   ├── controller.py
│   ├── permissions.py
│   ├── clear_state_program.py
├── scripts
│   ├── 0-setup-token.js
│   ├── 1-setup-controller.js
│   ├── 2-asset-clawback.js
│   ├── 3-setup-permissions.js
|   ├── admin
│   │   ├── issue.js
│   │   ├── force-transfer.js
│   │   ├── kill.js
│   │   ├── update-reserve.js
|   ├── permissions
│   │   ├── change-perm-manager.js
│   │   ├── whitelist.js
|   ├── user
│   │   ├── opt-out.js
│   │   ├── transfer.js
├── test
│   ├── JS test files
├── package.json

const owner = deployer.accountsByName.get('alice');
// deploy ASA by owner account
return await deployer.deployASA(tesla', { creator: owner });

# retreive asset manager from Txn.ForeignAssets[0]
assetManager = AssetParam.manager(Int(0))
on_deployment = Seq([
    assetManager, # load asset manager from store
    Assert(And(
        Txn.assets.length() == Int(1),
        Txn.assets[0] == Int(TOKEN_ID),

        # Controller should be deployed by ASA.manager
        Txn.sender() == assetManager.value()
    )),
    # set kill_status to false(0)
    App.globalPut(var_is_killed, Int(0)),
    Return(Int(1))
])

const tesla = deployer.asa.get('tesla'); // load asset info from checkpoint

const templateParam = {
  TOKEN_ID: tesla.assetIndex
};

await deployer.deploySSC(
'controller.py', // approval program
'clear_state_program.py', // clear program
{
  sender: owner,
  localInts: 0,
  localBytes: 0,
  globalInts: 2, // 1 to store kill_status, 1 for storing permissions_app_id
  globalBytes: 0,
  foreignAssets: [tesla.assetIndex] // pass token_id in foreign assets array
}, {}, templateParam); // pass token_id as a template paramenter

// load asset, controller ssc info from checkpoint
const tesla = deployer.asa.get('tesla');
const controllerInfo = deployer.getSSC('controller.py', 'clear_state_program.py');

// Compile and fund clawback account. Logic sig is represent by a TEAL code.
// NOTE: we always need to use same template parameters otherwise the generated
//       lsig will be different.
// We use algob template functionality
// https://algobuilder.dev/guide/py-teal.html#external-parameters-support
const clawbackParams = { // template params
    TOKEN_ID: tesla.assetIndex,
    CONTROLLER_APP_ID: controllerInfo.appID
};

await deployer.fundLsig('clawback.py',
{ funder: owner, fundingMicroAlgo: 5e6 }, {}, clawbackParams); // sending 5 Algo

// Update clawback address to clawback lsig
const clawbackLsig = await deployer.loadLogic('clawback.py', clawbackParams);
const clawbackAddress = clawbackLsig.address();
const assetConfigParams = {
    type: TransactionType.ModifyAsset,
    sign: SignType.SecretKey,
    fromAccount: owner,
    assetID: tesla.assetIndex,
    fields: { clawback: clawbackAddress },
    payFlags: { totalFee: 1000 }
};
await executeTransaction(deployer, assetConfigParams);

permissions_manager = Bytes("manager")  # permissions manager (manages contract permissions)
max_tokens = Bytes("max_tokens") # maximum token transfer rule
whitelist_count = Bytes("whitelist_count") # whitelisted accounts counter
# During deployment
# * max_tokens is set to 100
# * whitelist_counter is intialized to 0
# * save permissions manager in global state
on_deployment = Seq([
    Assert(basic_checks), # closeRemTo, rekey ..etc
    App.globalPut(max_tokens, Int(100)),
    App.globalPut(whitelist_count, Int(0)),
    App.globalPut(permissions_manager, Addr(PERM_MANAGER)),
    Return(Int(1))
])

const controllerSSCInfo = deployer.getSSC('controller.py', 'clear_state_program.py');
// We use algob template functionality
// https://algobuilder.dev/guide/py-teal.html#external-parameters-support
const templateParam = { PERM_MANAGER: owner.addr };

/** Deploy Permissions(rules) smart contract **/
const permissionSSCInfo = await deployer.deploySSC(
'permissions.py', // approval program
'clear_state_program.py', // clear program
{
  sender: owner,
  localInts: 1, // 1 to store whitelisted status in local state
  localBytes: 0,
  globalInts: 2, // 1 to store max_tokens, 1 for storing total whitelisted accounts
  globalBytes: 1 // to store permissions manager
}, {}, templateParam); // pass perm_manager as a template param (to set during deploy)
console.log(permissionSSCInfo);

const tesla = deployer.asa.get('tesla');
// retrive the permissions smart contract object from checkpoint
const permissionSSCInfo = deployer.getSSC('permissions.py', 'clear_state_program.py');
const appArgs = [
  'str:set_permission',
  `int:${permissionSSCInfo.appID}`
];

await executeTransaction(deployer, {
  type: TransactionType.CallNoOpSSC,
  sign: SignType.SecretKey,
  fromAccount: owner, // ASA manager account
  appId: controllerSSCInfo.appID,
  payFlags: { totalFee: 1000 },
  appArgs: appArgs,
  foreignAssets: [tesla.assetIndex] // controller sc verifies if correct token is being used + asa.manager is correct one
});

assetManager = AssetParam.manager(Int(0))
set_permission_contract = Seq([
    assetManager, # load asset_manager (from Store) of Txn.ForeignAssets[0]
    Assert(And(
        Txn.application_args.length() == Int(2),
        Txn.assets.length() == Int(1),
        Txn.assets[0] == Int(TOKEN_ID),
        Txn.sender() == assetManager.value(),
    )),
    # Add permissions(rules) smart contract app_id in global state
    App.globalPut(permission_id, Btoi(Txn.application_args[1])),
    Return(Int(1))
])

// load asset, controller info from checkpoint
const tesla = deployer.asa.get('tesla');
const controllerSSCInfo = deployer.getSSC('controller.py', 'clear_state_program.py');

const issuanceParams = [
  /*
   * tx 0 - Call to controller stateful smart contract with application arg: 'issue'
   * The 'issue' branch ensures that sender is the token reserve and token is not killed
   * Issuance tx will be rejected if token has been killed by the manager */
  {
    type: TransactionType.CallNoOpSSC,
    sign: SignType.SecretKey,
    fromAccount: asaReserve,
    appId: controllerSSCInfo.appID,
    payFlags: { totalFee: 1000 },
    appArgs: ['str:issue'],
    foreignAssets: [tesla.assetIndex]
  },
  /*
   * tx 1 - Asset transfer transaction from sender -> receiver. This tx is executed
   * and approved by the clawback lsig (clawback.teal). The clawback lsig address is the
   * address which transfers the frozen asset (amount = amount) from accA to accB.
   * Clawback ensures a call to controller smart contract during token transfer. */
  {
    type: TransactionType.RevokeAsset,
    sign: SignType.LogicSignature,
    fromAccountAddr: clawbackAddress,
    recipient: address,
    assetID: tesla.assetIndex,
    revocationTarget: asaReserve.addr, // tx will fail if assetSender is not token reserve address
    amount: amount,
    lsig: clawbackLsig,
    payFlags: { totalFee: 1000 }
  }
];

await executeTransaction(deployer, issuanceParams);

// owner account was set as the permissions_manager during deploy
const whiteListParams = {
  type: TransactionType.CallNoOpSSC,
  sign: SignType.SecretKey,
  fromAccount: permissionsManager, // permissions manager account (fails otherwise)
  appId: permissionSSCInfo.appID,
  payFlags: { totalFee: 1000 },
  appArgs: ['str:add_whitelist'],
  accounts: [address] // pass address to add to whitelisted addresses
};

await executeTransaction(deployer, whiteListParams);

add_whitelist = Seq([
    Assert(And(
        Txn.accounts.length() == Int(1),
        basic_checks,

        # verify txn sender is the permissions manager
        Txn.sender() == App.globalGet(permissions_manager),
    )),

    If(
        # increment counter if account is not already whitelisted
        App.localGet(Int(1), Bytes("whitelisted")) == Int(0),
        App.globalPut(whitelist_count, App.globalGet(whitelist_count) + Int(1)),
        Return(Int(1))
    ),

    # update Txn.accounts[1] local state to set whitelisted status as true(1)
    App.localPut(Int(1), Bytes("whitelisted"), true),
    Return(Int(1))
])

const tesla = deployer.asa.get('tesla');

const txGroup = [
  /*
   * tx 0 - Call to controller stateful smart contract with application arg: 'transfer'
   * The contract ensures that there is a call to permissions smart contract in the txGroup,
   * so that rules are checked during token transfer.
   */
  {
    type: TransactionType.CallNoOpSSC,
    sign: SignType.SecretKey,
    fromAccount: from,
    appId: controllerSSCInfo.appID,
    payFlags: { totalFee: 1000 },
    appArgs: ['str:transfer']
  },
  /*
   * tx 1 - Asset transfer transaction from sender -> receiver. This tx is executed
   * and approved by the clawback lsig (clawback.py). The lsig address is
   * also the clawback address which transfers the frozen asset from accA to accB.
   * Clawback ensures a call to controller smart contract during token transfer. */
  {
    type: TransactionType.RevokeAsset,
    sign: SignType.LogicSignature,
    fromAccountAddr: clawbackAddress,
    recipient: toAddr,
    assetID: tesla.assetIndex,
    revocationTarget: from.addr,
    amount: amount,
    lsig: clawbackLsig,
    payFlags: { totalFee: 1000 }
  },
  /*
   * tx 2 - Payment transaction of 1000 microAlgo to cover clawback transaction cost (tx 1)
   * NOTE: It can be signed by any account, but it must be present in group. */
  {
    type: TransactionType.TransferAlgo,
    sign: SignType.SecretKey,
    fromAccount: from,
    toAccountAddr: clawbackAddress,
    amountMicroAlgos: 1000,
    payFlags: { totalFee: 1000 }
  },
  /*
   * tx 3 - Call to permissions stateful smart contract with application arg: 'transfer'
   * The contract ensures that both accA & accB is whitelisted and asset_receiver does not hold more than 100 tokens. */
  {
    type: TransactionType.CallNoOpSSC,
    sign: SignType.SecretKey,
    fromAccount: from,
    appId: permissionsSSCInfo.appID,
    payFlags: { totalFee: 1000 },
    appArgs: ['str:transfer'],
    accounts: [from.addr, toAddr] //  AppAccounts (pass asset sender & receiver address)
  }
];

await executeTransaction(deployer, txGroup);

# fetch asset_holding.balance from Txn.accounts[2] (asset_receiver)
asset_balance = AssetHolding.balance(Int(2), Gtxn[1].xfer_asset())

# Transfer token from accA -> accB. Both A, B are non-reserve accounts.
# Expected arguments (fetched from Txn.Accounts array):
# * fromAccountAddress
# * toAccountAddress
transfer_token = Seq([
    asset_balance, # load asset_balance of asset_receiver from store
    Assert(And(
        Gtxn[1].type_enum() == TxnType.AssetTransfer, # this should be clawback call

        # verify [from, to] addresses (from Txn.accounts) of current_tx
        # should be same as [asset_sender, asset_receiver]
        Txn.accounts[1] == Gtxn[1].asset_sender(),
        Txn.accounts[2] == Gtxn[1].asset_receiver(),

        # rule 1 - check balance of receiver after receiving token <= 100(max_tokens)
        asset_balance.value() <= App.globalGet(max_tokens),

        # rule 2 - [from, to] accounts must be whitelisted
        # NOTE: Int(0) == Txn.Sender(), Int(1) == Txn.accounts[1]
        App.localGet(Int(1), Bytes("whitelisted")) == true, # from account must be whitelisted
        App.localGet(Int(2), Bytes("whitelisted")) == true  # to account must be whitelisted
    )),
    Return(Int(1))
])

const asaManager = deployer.accountsByName.get('alice'); // alice is set as the permissions_manager during deploy
const tesla = deployer.asa.get('tesla');
const controllerSSCInfo = deployer.getSSC('controller.py', clearStateProgram);
const permissionsSSCInfo = deployer.getSSC('permissions.py', clearStateProgram);

// notice the difference in calls here: stateful calls are done by token manager here
// and from, to address are only used in asset transfer tx
const forceTxGroup = [
  /*
   * tx 0 - Call to controller stateful smart contract (by ASA.manager)
   * with application arg: 'force_transfer'. The contract ensures that there
   * is a call to permissions smart contract in the txGroup, so that rules
   * are checked during token transfer. */
  {
    type: types.TransactionType.CallNoOpSSC,
    sign: types.SignType.SecretKey,
    fromAccount: asaManager,
    appId: controllerSSCInfo.appID,
    payFlags: { totalFee: 1000 },
    appArgs: ['str:force_transfer'],
    foreignAssets: [tesla.assetIndex] // to verify token reserve, manager
  },
  /*
   * tx 1 - Asset transfer transaction from sender -> receiver. This tx is executed
   * and approved by the clawback lsig (clawback.teal). The clawback lsig address is the
   * address which transfers the frozen asset (amount = amount) from accA to accB.
   * Clawback ensures a call to controller smart contract during token transfer. */
  {
    type: types.TransactionType.RevokeAsset,
    sign: types.SignType.LogicSignature,
    fromAccountAddr: clawbackAddress,
    recipient: toAddr,
    assetID: tesla.assetIndex,
    revocationTarget: fromAddr,
    amount: amount,
    lsig: clawbackLsig,
    payFlags: { totalFee: 1000 }
  },
  /*
   * tx 2 - Payment transaction of 1000 microAlgo to cover clawback transaction cost (tx 1).
   * NOTE: It can be signed by any account, but it should be present in group. */
  {
    type: types.TransactionType.TransferAlgo,
    sign: types.SignType.SecretKey,
    fromAccount: asaManager,
    toAccountAddr: clawbackAddress,
    amountMicroAlgos: 1000,
    payFlags: { totalFee: 1000 }
  },
  /*
   * tx 3 - Call to permissions stateful smart contract with application arg: 'transfer' */
  {
    type: types.TransactionType.CallNoOpSSC,
    sign: types.SignType.SecretKey,
    fromAccount: asaManager,
    appId: permissionsSSCInfo.appID,
    payFlags: { totalFee: 1000 },
    appArgs: ['str:transfer'],
    accounts: [fromAddr, toAddr] //  AppAccounts (pass asset sender & receiver address)
  }
];

await executeTransaction(deployer, forceTxGroup);

# Check permissions smart contract is called and it's application index is correct
verify_perm_is_called = And(
    # verify rules call (ensure permissions smart contract is being called in 4th tx)
    Gtxn[3].type_enum() == TxnType.ApplicationCall,
    Gtxn[3].application_id() == App.globalGet(permission_id),
)

# retreive asset manager, reserve from Txn.ForeignAssets[0]
assetManager = AssetParam.manager(Int(0))
assetReserve = AssetParam.reserve(Int(0))

# Force transfer (clawback) some tokens between two accounts.
# Only accepted if token is not killed and sender is asset manager.
# NOTE: If the asset_receiver is the reserve address (current one, or the new one being set
# in the asset config txn in group while updating reserve), then we don't need to verify
# permissions is called - it can bypass rule(s) checks.
force_transfer = Seq([
    assetManager,
    assetReserve,
    Assert(And(
        App.globalGet(var_is_killed) == Int(0), # check token is not killed
        verify_basic_calls,
        Txn.sender() == assetManager.value(), # force_transfer is only allowed by asset manager
    )),
    Return(
        If(
            Or(
                # If the receiver is the reserve address - old, or the new one being updated in the assset config tx (Gtxn[3]),
                # then it can bypass permission checks
                Gtxn[1].asset_receiver() == assetReserve.value(),
                If(Global.group_size() > Int(3), Gtxn[1].asset_receiver() == Gtxn[3].config_asset_reserve(), Int(0))
            ),
            Int(1),
            # else verify that permissions ssc is called
            verify_perm_is_called
        )
    )
])

it('should issue token if sender is token reserve', () => {
  // setup token & deploy contracts
  ctx = new Context(master, alice, bob, elon);

  // Can issue after opting-in
  ctx.optInToASA(elon.address);

  const prevElonAssetHolding = ctx.getAssetHolding(elon.address);
  assert.equal(prevElonAssetHolding.amount, 0n);

  // issue 20 tokens to elon from reserve
  ctx.issue(asaReserve.account, elon, 20);
  ctx.syncAccounts(); // refresh accounts

  assert.equal(
    ctx.getAssetHolding(elon.address).amount,
    prevElonAssetHolding.amount + 20n
  );
});

it('should reject issuance tx if sender is not token reserve', () => {
  ctx.optInToASA(elon.address);

  // verify bob is not asa.reserve
  const asaDef = ctx.getAssetDef();
  const asaReserve = ctx.getAccount(asaDef.reserve);
  assert.notEqual(asaReserve, bob.address);

  assert.throws(() => ctx.issue(bob.account, elon, 20),
    'RUNTIME_ERR1009: TEAL runtime encountered err opcode');
});