Merge pull request #66 from project-serum/armani/realize

Program interfaces

.travis.yml

@@ -49,6 +49,7 @@ jobs:
         - pushd examples/errors && anchor test && popd
         - pushd examples/spl/token-proxy && anchor test && popd
         - pushd examples/multisig && anchor test && popd
+        - pushd examples/interface && anchor test && popd
         - pushd examples/tutorial/basic-0 && anchor test && popd
         - pushd examples/tutorial/basic-1 && anchor test && popd
         - pushd examples/tutorial/basic-2 && anchor test && popd

CHANGELOG.md

@@ -11,6 +11,12 @@ incremented for features.
 
 ## [Unreleased]
 
+### Features
+
+* lang: Adds the ability to create and use CPI program interfaces [(#66)](https://github.com/project-serum/anchor/pull/66/files?file-filters%5B%5D=).
+
+### Breaking Changes
+
 * lang, client, ts: Migrate from rust enum based method dispatch to a variant of sighash [(#64)](https://github.com/project-serum/anchor/pull/64).
 
 ## [0.1.0] - 2021-01-31

examples/interface/Anchor.toml

@@ -0,0 +1,2 @@
+cluster = "localnet"
+wallet = "~/.config/solana/id.json"

examples/interface/Cargo.toml

@@ -0,0 +1,4 @@
+[workspace]
+members = [
+    "programs/*"
+]

examples/interface/programs/counter-auth/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "counter-auth"
+version = "0.1.0"
+description = "Created with Anchor"
+edition = "2018"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "counter_auth"
+
+[features]
+no-entrypoint = []
+no-idl = []
+cpi = ["no-entrypoint"]
+default = []
+
+[dependencies]
+anchor-lang = { git = "https://github.com/project-serum/anchor" }
+counter = { path = "../counter", features = ["cpi"] }

examples/interface/programs/counter-auth/Xargo.toml

@@ -0,0 +1,2 @@
+[target.bpfel-unknown-unknown.dependencies.std]
+features = []

examples/interface/programs/counter-auth/src/lib.rs

@@ -0,0 +1,43 @@
+//! counter-auth is an example of a program *implementing* an external program
+//! interface. Here the `counter::Auth` trait, where we only allow a count
+//! to be incremented if it changes the counter from odd -> even or even -> odd.
+//! Creative, I know. :P.
+
+#![feature(proc_macro_hygiene)]
+
+use anchor_lang::prelude::*;
+use counter::Auth;
+
+#[program]
+pub mod counter_auth {
+    use super::*;
+
+    #[state]
+    pub struct CounterAuth {}
+
+    // TODO: remove this impl block after addressing
+    //       https://github.com/project-serum/anchor/issues/71.
+    impl CounterAuth {
+        pub fn new(_ctx: Context<Empty>) -> Result<Self, ProgramError> {
+            Ok(Self {})
+        }
+    }
+
+    impl<'info> Auth<'info, Empty> for CounterAuth {
+        fn is_authorized(_ctx: Context<Empty>, current: u64, new: u64) -> ProgramResult {
+            if current % 2 == 0 {
+                if new % 2 == 0 {
+                    return Err(ProgramError::Custom(50)); // Arbitrary error code.
+                }
+            } else {
+                if new % 2 == 1 {
+                    return Err(ProgramError::Custom(60)); // Arbitrary error code.
+                }
+            }
+            Ok(())
+        }
+    }
+}
+
+#[derive(Accounts)]
+pub struct Empty {}

examples/interface/programs/counter/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "counter"
+version = "0.1.0"
+description = "Created with Anchor"
+edition = "2018"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "counter"
+
+[features]
+no-entrypoint = []
+no-idl = []
+cpi = ["no-entrypoint"]
+default = []
+
+[dependencies]
+anchor-lang = { git = "https://github.com/project-serum/anchor" }

examples/interface/programs/counter/Xargo.toml

@@ -0,0 +1,2 @@
+[target.bpfel-unknown-unknown.dependencies.std]
+features = []

examples/interface/programs/counter/src/lib.rs

@@ -0,0 +1,73 @@
+//! counter is an example program that depends on an external interface
+//! that another program must implement. This allows our program to depend
+//! on another program, without knowing anything about it other than the fact
+//! that it implements the `Auth` trait.
+//!
+//! Here, we have a counter, where, in order to set the count, the `Auth`
+//! program must first approve the transaction.
+
+#![feature(proc_macro_hygiene)]
+
+use anchor_lang::prelude::*;
+
+#[program]
+pub mod counter {
+    use super::*;
+
+    #[state]
+    pub struct Counter {
+        pub count: u64,
+        pub auth_program: Pubkey,
+    }
+
+    impl Counter {
+        pub fn new(_ctx: Context<Empty>, auth_program: Pubkey) -> Result<Self> {
+            Ok(Self {
+                count: 0,
+                auth_program,
+            })
+        }
+
+        #[access_control(SetCount::accounts(&self, &ctx))]
+        pub fn set_count(&mut self, ctx: Context<SetCount>, new_count: u64) -> Result<()> {
+            // Ask the auth program if we should approve the transaction.
+            let cpi_program = ctx.accounts.auth_program.clone();
+            let cpi_ctx = CpiContext::new(cpi_program, Empty {});
+            auth::is_authorized(cpi_ctx, self.count, new_count)?;
+
+            // Approved, so update.
+            self.count = new_count;
+            Ok(())
+        }
+    }
+}
+
+#[derive(Accounts)]
+pub struct Empty {}
+
+#[derive(Accounts)]
+pub struct SetCount<'info> {
+    auth_program: AccountInfo<'info>,
+}
+
+impl<'info> SetCount<'info> {
+    // Auxiliary account validation requiring program inputs. As a convention,
+    // we separate it from the business logic of the instruction handler itself.
+    pub fn accounts(counter: &Counter, ctx: &Context<SetCount>) -> Result<()> {
+        if ctx.accounts.auth_program.key != &counter.auth_program {
+            return Err(ErrorCode::InvalidAuthProgram.into());
+        }
+        Ok(())
+    }
+}
+
+#[interface]
+pub trait Auth<'info, T: Accounts<'info>> {
+    fn is_authorized(ctx: Context<T>, current: u64, new: u64) -> ProgramResult;
+}
+
+#[error]
+pub enum ErrorCode {
+    #[msg("Invalid auth program.")]
+    InvalidAuthProgram,
+}

examples/interface/tests/interface.js

@@ -0,0 +1,45 @@
+const anchor = require('@project-serum/anchor');
+const assert = require("assert");
+
+describe("interface", () => {
+  // Configure the client to use the local cluster.
+  anchor.setProvider(anchor.Provider.env());
+
+  const counter = anchor.workspace.Counter;
+  const counterAuth = anchor.workspace.CounterAuth;
+  it("Is initialized!", async () => {
+    await counter.state.rpc.new(counterAuth.programId);
+
+    const stateAccount = await counter.state();
+    assert.ok(stateAccount.count.eq(new anchor.BN(0)));
+    assert.ok(stateAccount.authProgram.equals(counterAuth.programId));
+  });
+
+  it("Should fail to go from even to event", async () => {
+    await assert.rejects(
+      async () => {
+        await counter.state.rpc.setCount(new anchor.BN(4), {
+          accounts: {
+            authProgram: counterAuth.programId,
+          },
+        });
+      },
+      (err) => {
+        if (err.toString().split("custom program error: 0x32").length !== 2) {
+          return false;
+        }
+        return true;
+      }
+    );
+  });
+
+  it("Shold succeed to go from even to odd", async () => {
+    await counter.state.rpc.setCount(new anchor.BN(3), {
+      accounts: {
+        authProgram: counterAuth.programId,
+      },
+    });
+    const stateAccount = await counter.state();
+    assert.ok(stateAccount.count.eq(new anchor.BN(3)));
+  });
+});

examples/lockup/programs/lockup/src/lib.rs

@@ -74,6 +74,7 @@ pub mod lockup {
         period_count: u64,
         deposit_amount: u64,
         nonce: u8,
+        realizor: Option<Realizor>,
     ) -> Result<()> {
         if end_ts <= ctx.accounts.clock.unix_timestamp {
             return Err(ErrorCode::InvalidTimestamp.into());
@@ -100,12 +101,14 @@ pub mod lockup {
         vesting.whitelist_owned = 0;
         vesting.grantor = *ctx.accounts.depositor_authority.key;
         vesting.nonce = nonce;
+        vesting.realizor = realizor;
 
         token::transfer(ctx.accounts.into(), deposit_amount)?;
 
         Ok(())
     }
 
+    #[access_control(is_realized(&ctx))]
     pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
         // Has the given amount vested?
         if amount
@@ -187,7 +190,7 @@ pub mod lockup {
         Ok(())
     }
 
-    // Convenience function for UI's to calculate the withdrawalable amount.
+    // Convenience function for UI's to calculate the withdrawable amount.
     pub fn available_for_withdrawal(ctx: Context<AvailableForWithdrawal>) -> Result<()> {
         let available = calculator::available_for_withdrawal(
             &ctx.accounts.vesting,
@@ -242,6 +245,8 @@ impl<'info> CreateVesting<'info> {
     }
 }
 
+// All accounts not included here, i.e., the "remaining accounts" should be
+// ordered according to the realization interface.
 #[derive(Accounts)]
 pub struct Withdraw<'info> {
     // Vesting.
@@ -327,6 +332,29 @@ pub struct Vesting {
     pub whitelist_owned: u64,
     /// Signer nonce.
     pub nonce: u8,
+    /// The program that determines when the locked account is **realized**.
+    /// In addition to the lockup schedule, the program provides the ability
+    /// for applications to determine when locked tokens are considered earned.
+    /// For example, when earning locked tokens via the staking program, one
+    /// cannot receive the tokens until unstaking. As a result, if one never
+    /// unstakes, one would never actually receive the locked tokens.
+    pub realizor: Option<Realizor>,
+}
+
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug)]
+pub struct Realizor {
+    /// Program to invoke to check a realization condition. This program must
+    /// implement the `RealizeLock` trait.
+    pub program: Pubkey,
+    /// Address of an arbitrary piece of metadata interpretable by the realizor
+    /// program. For example, when a vesting account is allocated, the program
+    /// can define its realization condition as a function of some account
+    /// state. The metadata is the address of that account.
+    ///
+    /// In the case of staking, the metadata is a `Member` account address. When
+    /// the realization condition is checked, the staking program will check the
+    /// `Member` account defined by the `metadata` has no staked tokens.
+    pub metadata: Pubkey,
 }
 
 #[derive(AnchorSerialize, AnchorDeserialize, PartialEq, Default, Copy, Clone)]
@@ -366,6 +394,12 @@ pub enum ErrorCode {
     WhitelistEntryNotFound,
     #[msg("You do not have sufficient permissions to perform this action.")]
     Unauthorized,
+    #[msg("You are unable to realize projected rewards until unstaking.")]
+    UnableToWithdrawWhileStaked,
+    #[msg("The given lock realizor doesn't match the vesting account.")]
+    InvalidLockRealizor,
+    #[msg("You have not realized this vesting account.")]
+    UnrealizedVesting,
 }
 
 impl<'a, 'b, 'c, 'info> From<&mut CreateVesting<'info>>
@@ -456,3 +490,34 @@ fn whitelist_auth(lockup: &Lockup, ctx: &Context<Auth>) -> Result<()> {
     }
     Ok(())
 }
+
+// Returns Ok if the locked vesting account has been "realized". Realization
+// is application dependent. For example, in the case of staking, one must first
+// unstake before being able to earn locked tokens.
+fn is_realized<'info>(ctx: &Context<Withdraw>) -> Result<()> {
+    if let Some(realizor) = &ctx.accounts.vesting.realizor {
+        let cpi_program = {
+            let p = ctx.remaining_accounts[0].clone();
+            if p.key != &realizor.program {
+                return Err(ErrorCode::InvalidLockRealizor.into());
+            }
+            p
+        };
+        let cpi_accounts = ctx.remaining_accounts.to_vec()[1..].to_vec();
+        let cpi_ctx = CpiContext::new(cpi_program, cpi_accounts);
+        let vesting = (*ctx.accounts.vesting).clone();
+        realize_lock::is_realized(cpi_ctx, vesting).map_err(|_| ErrorCode::UnrealizedVesting)?;
+    }
+    Ok(())
+}
+
+/// RealizeLock defines the interface an external program must implement if
+/// they want to define a "realization condition" on a locked vesting account.
+/// This condition must be satisfied *even if a vesting schedule has
+/// completed*. Otherwise the user can never earn the locked funds. For example,
+/// in the case of the staking program, one cannot received a locked reward
+/// until one has completely unstaked.
+#[interface]
+pub trait RealizeLock<'info, T: Accounts<'info>> {
+    fn is_realized(ctx: Context<T>, v: Vesting) -> ProgramResult;
+}