With the new separation of staker and worker (#1029, #1003, #1054), we also permit an interesting use-case which we are not handling yet in the python codebase: the possibility that the staker in the StakingEscrow contract is another contract. This must be the case for contracts like UserEscrow. For the sake of argument, let's call this type of stakers PuppetStaker, while the traditional, flesh-and-blood staker can be HumanStaker.

We have then two types of use cases:

+--------------+            +---------------+                                                
|  HumanStaker |  controls  |  PuppetStaker |                                                
|              ------------->               |                                                
|    0xFACE    |            |     0xABCD    |                                                
+--------------+            +---------------+    +----------------------+                 
                                |                |     StakingEscrow    |                 
                                |                |                      |                 
                                |                |  staker      worker  |                 
                                |                | ----------|--------- |                 
                                +--------------->|  0xABCD   |  0x1234  |                 
                                  interacts with |           |          |                 
                                +--------------->|  0xCAFE   |  0x9876  |                 
                                |                +----------------------+                 
                                |                                                         
                          +--------------+                                                
                          | HumanStaker  |                                                
                          |              |                                                
                          |    0xCAFE    |                                                
                          +--------------+                                                
                                                                             

From the perspective of our contracts and also the python codebase, we are mostly concerned about the one who's in StakingEscrow (i.e., the acting staker), regardless of being human or puppet. In the diagram, these are 0xABCD and 0xCAFE. That means that from the point of view of our Actor abstraction, both can be represented by the Staker class. However, from the viewpoint of the HumanStaker, she can be interacting with StakingEscrow through 0, 1 or a chain of N puppets.

While writing this issue my understanding is evolving, and I think we can consider two different dimensions to understand this problem:

• Human/Puppet (as explained above)
• On-stage/Off-stage: When this actor/entity is in StakingEscrow, we say it's "on-stage"; otherwise, it's "off-stage".

From the combination of both dimensions we have:

• On-stage Human: Traditional stakers ("John Doe has an ETH account holding NU tokens, which is included in StakingEscrow"). In the example above, 0xCAFE is an on-stage human.
• On-stage Puppet: A contract that is acting as staker. For example, UserEscrow contracts. Who knows what other types of contracts external to NuCypher can act as on-stage puppets too. In the example above, 0xABCD is an on-stage puppet.
• Off-stage Human: The human behind a puppet, the Master of Puppets (e.g., the "User" in UserEscrow). In the example above, 0xFACE is an off-stage human.
• Off-stage Puppet: In principle, our contracts allow the possibility of a chain of off-stage puppets controlling an on-stage puppet, at the end controlled by an off-stage human. However, we don't need to do anything in our python codebase to support this, IMO.