Delegation

The Delegation pattern gives one party the right to exercise a choice on behalf of another party. The agent can control a contract instance on the ledger without the principal explicitly committing the action.

Motivation

Delegation is prevalent in the business world. In fact, the entire custodian business is based on delegation. When a company chooses a custodian bank, it is effectively giving the bank the rights to hold their securities and settle transactions on their behalf. The securities are not legally possessed by the custodian banks, but the banks should have full rights to perform actions in the client’s name, such as making payments or changing investments.

The Delegation pattern enables DAML modelers to model the real-world business contractual agreements between custodian banks and their customers. Ownership and administration rights can be segregated easily and clearly.

Implementation

Pre-condition: There exists a contract, on which controller Party A has a choice and intends to delegate execution of the choice to Party B. In this example, the owner of a Coin contract intends to delegate the Transfer choice.

--the original contract
template Coin
  with
    owner: Party
    issuer: Party
    amount: Decimal
    delegates : [Party]
  where
    signatory issuer, owner
    observer delegates

    controller owner can

      Transfer : ContractId TransferProposal
        with newOwner: Party
        do   
            create TransferProposal
             with coin=this; newOwner

      Lock : ContractId LockedCoin
        with maturity: Time; locker: Party
        do create LockedCoin with coin=this; maturity; locker

      Disclose : ContractId Coin
        with p : Party
        do create this with delegates = p :: delegates

    --a coin can only be archived by the issuer under the condition that the issuer is the owner of the coin. This ensures the issuer cannot archive coins at will.
    controller issuer can
      Archives
        : ()
        do assert (issuer == owner)

Delegation Contract

• Principal, the original coin owner, is the signatory of delegation contract CoinPoA. This signatory is required to authorize the Transfer choice on coin.

template CoinPoA
  with
    attorney: Party
    principal: Party
  where
    signatory principal
    
    controller principal can
      WithdrawPoA
        : ()
        do return ()

• Whether or not the Attorney party should be a signatory of CoinPoA is subject to the business agreements between Principal and Attorney. For simplicity, in this example, Attorney is not a signatory.
• Attorney is the controller of the Delegation choice on the contract. Within the choice, Principal exercises the choice Transfer on the Coin contract.

    controller attorney can
      nonconsuming TransferCoin
        : ContractId TransferProposal
        with
          coinId: ContractId Coin
          newOwner: Party
        do            
          exercise coinId Transfer with newOwner

• Coin contracts need to be disclosed to Attorney before they can be used in an exercise of Transfer. This can be done by adding Attorney to Coin as an Observer. This can be done dynamically, for any specific Coin, by making the observers a List, and adding a choice to add a party to that List:

      Disclose : ContractId Coin
        with p : Party
        do create this with delegates = p :: delegates

Note

The technique is likely to change in the future. DAML is actively researching future language features for contract disclosure.

Delegation pattern diagram