ACS9 - 合约利润分红标准¶
在AElf的侧链中，合约需要声明自己所得盈利的去向，这时候就需要实现ACS9中定义的一些方法。
接口¶
ACS9 contains an method which does not have to be implemented:
- TakeContractProfits，用于开发者领取合约的利润，同时会在该方法中分配利润，其参数中需要制定本次领取的利润的代币symbol和数额。开发者也可以使用其他的方法来领取利润。不过相应的逻辑都需要审核通过才可以部署/升级。
两个必须实现以便于显示在AElf区块链浏览器的View方法：
- GetProfitConfig，其返回值是acs9.proto中定义的ProfitConfig数据结构，该结构中包括利润代币symbol列表、用户为了领取利润而锁仓的代币symbol，以及每次开发者领取利润时，其中会捐赠给分红池的部分。在审核该合约的代码时，需要查看实际分配利润的代码逻辑是否使用了同样的ProfitConfig数据。
- GetProfitsAmount，顾名思义，就是查询该合约目前获得的利润，返回值为ProfitsMap类型。
ProfitConfig的定义为：
message ProfitConfig {
int32 donation_parts_per_hundred = 1;
repeated string profits_token_symbol_list = 2;
string staking_token_symbol = 3;
}
ProfitsMap类型实质上就是代币symbol和相应数额的map：
message ProfitsMap {
map<string, int64> value = 1;
}
接口实现¶
在这里我们定义一个合约。该合约会在初始化的时候创建一种名为APP的代币，并使用TokenHolder合约创建出来一个持币人分红方案，锁仓币种指定为APP。
在用户SignUp时，给用户10个APP。
用户可以使用Deposit方法1：1消耗ELF购买APP，也可以使用Withdraw方法赎回ELF，归还等量的APP给合约。
当用户调用Use方法时，会消耗APP代币。
合约初始化如下：
public override Empty Initialize(InitializeInput input)
{
State.TokenHolderContract.Value =
Context.GetContractAddressByName(SmartContractConstants.TokenHolderContractSystemName);
State.TokenContract.Value =
Context.GetContractAddressByName(SmartContractConstants.TokenContractSystemName);
State.DividendPoolContract.Value =
Context.GetContractAddressByName(input.DividendPoolContractName.Value.ToBase64());
State.Symbol.Value = input.Symbol == string.Empty ? "APP" : input.Symbol;
State.ProfitReceiver.Value = input.ProfitReceiver;
CreateToken(input.ProfitReceiver);
// To test TokenHolder Contract.
CreateTokenHolderProfitScheme();
// To test ACS9 workflow.
SetProfitConfig();
State.ProfitReceiver.Value = input.ProfitReceiver;
return new Empty();
}
private void CreateToken(Address profitReceiver, bool isLockWhiteListIncludingSelf = false)
{
var lockWhiteList = new List<Address>
{Context.GetContractAddressByName(SmartContractConstants.TokenHolderContractSystemName)};
if (isLockWhiteListIncludingSelf)
lockWhiteList.Add(Context.Self);
State.TokenContract.Create.Send(new CreateInput
{
Symbol = State.Symbol.Value,
TokenName = "DApp Token",
Decimals = ACS9DemoContractConstants.Decimal,
Issuer = Context.Self,
IsBurnable = true,
IsProfitable = true,
TotalSupply = ACS9DemoContractConstants.TotalSupply,
LockWhiteList =
{
lockWhiteList
}
});
State.TokenContract.Issue.Send(new IssueInput
{
To = profitReceiver,
Amount = ACS9DemoContractConstants.TotalSupply / 5,
Symbol = State.Symbol.Value,
Memo = "Issue token for profit receiver"
});
}
private void CreateTokenHolderProfitScheme()
{
State.TokenHolderContract.CreateScheme.Send(new CreateTokenHolderProfitSchemeInput
{
Symbol = State.Symbol.Value
});
}
private void SetProfitConfig()
{
State.ProfitConfig.Value = new ProfitConfig
{
DonationPartsPerHundred = 1,
StakingTokenSymbol = "APP",
ProfitsTokenSymbolList = {"ELF"}
};
}
其中，State.Symbol为string类型的单例，State.ProfitConfig为ProfitConfig类型的单例，State.ProfitReceiver为Address类型的单例。
用户使用SighUp方法可以注册领币，同时为他建立档案：
/// <summary>
/// When user sign up, give him 10 APP tokens, then initialize his profile.
/// </summary>
/// <param name="input"></param>
/// <returns></returns>
public override Empty SignUp(Empty input)
{
Assert(State.Profiles[Context.Sender] == null, "Already registered.");
var profile = new Profile
{
UserAddress = Context.Sender
};
State.TokenContract.Issue.Send(new IssueInput
{
Symbol = State.Symbol.Value,
Amount = ACS9DemoContractConstants.ForNewUser,
To = Context.Sender
});
// Update profile.
profile.Records.Add(new Record
{
Type = RecordType.SignUp,
Timestamp = Context.CurrentBlockTime,
Description = string.Format("{0} +{1}",State.Symbol.Value, ACS9DemoContractConstants.ForNewUser)
});
State.Profiles[Context.Sender] = profile;
return new Empty();
}
充值和赎回：
public override Empty Deposit(DepositInput input)
{
// User Address -> DApp Contract.
State.TokenContract.TransferFrom.Send(new TransferFromInput
{
From = Context.Sender,
To = Context.Self,
Symbol = "ELF",
Amount = input.Amount
});
State.TokenContract.Issue.Send(new IssueInput
{
Symbol = State.Symbol.Value,
Amount = input.Amount,
To = Context.Sender
});
// Update profile.
var profile = State.Profiles[Context.Sender];
profile.Records.Add(new Record
{
Type = RecordType.Deposit,
Timestamp = Context.CurrentBlockTime,
Description = string.Format("{0} +{1}", State.Symbol.Value, input.Amount)
});
State.Profiles[Context.Sender] = profile;
return new Empty();
}
public override Empty Withdraw(WithdrawInput input)
{
State.TokenContract.TransferFrom.Send(new TransferFromInput
{
From = Context.Sender,
To = Context.Self,
Symbol = State.Symbol.Value,
Amount = input.Amount
});
State.TokenContract.Transfer.Send(new TransferInput
{
To = Context.Sender,
Symbol = input.Symbol,
Amount = input.Amount
});
State.TokenHolderContract.RemoveBeneficiary.Send(new RemoveTokenHolderBeneficiaryInput
{
Beneficiary = Context.Sender,
Amount = input.Amount
});
// Update profile.
var profile = State.Profiles[Context.Sender];
profile.Records.Add(new Record
{
Type = RecordType.Withdraw,
Timestamp = Context.CurrentBlockTime,
Description = string.Format("{0} -{1}", State.Symbol.Value, input.Amount)
});
State.Profiles[Context.Sender] = profile;
return new Empty();
}
Use的实现中，直接将1/3的盈利打入持币人分红方案：
public override Empty Use(Record input)
{
State.TokenContract.TransferFrom.Send(new TransferFromInput
{
From = Context.Sender,
To = Context.Self,
Symbol = State.Symbol.Value,
Amount = ACS9DemoContractConstants.UseFee
});
if (input.Symbol == string.Empty)
input.Symbol = State.TokenContract.GetPrimaryTokenSymbol.Call(new Empty()).Value;
var contributeAmount = ACS9DemoContractConstants.UseFee.Div(3);
State.TokenContract.Approve.Send(new ApproveInput
{
Spender = State.TokenHolderContract.Value,
Symbol = input.Symbol,
Amount = contributeAmount
});
// Contribute 1/3 profits (ELF) to profit scheme.
State.TokenHolderContract.ContributeProfits.Send(new ContributeProfitsInput
{
SchemeManager = Context.Self,
Amount = contributeAmount,
Symbol = input.Symbol
});
// Update profile.
var profile = State.Profiles[Context.Sender];
profile.Records.Add(new Record
{
Type = RecordType.Withdraw,
Timestamp = Context.CurrentBlockTime,
Description = string.Format("{0} -{1}", State.Symbol.Value, ACS9DemoContractConstants.UseFee),
Symbol = input.Symbol
});
State.Profiles[Context.Sender] = profile;
return new Empty();
}
这个合约本身就实现完成了，接下来实现ACS9的几个方法，来完善这个合约的利润分配环节：
public override Empty TakeContractProfits(TakeContractProfitsInput input)
{
var config = State.ProfitConfig.Value;
// For Side Chain Dividends Pool.
var amountForSideChainDividendsPool = input.Amount.Mul(config.DonationPartsPerHundred).Div(100);
State.TokenContract.Approve.Send(new ApproveInput
{
Symbol = input.Symbol,
Amount = amountForSideChainDividendsPool,
Spender = State.DividendPoolContract.Value
});
State.DividendPoolContract.Donate.Send(new DonateInput
{
Symbol = input.Symbol,
Amount = amountForSideChainDividendsPool
});
// For receiver.
var amountForReceiver = input.Amount.Sub(amountForSideChainDividendsPool);
State.TokenContract.Transfer.Send(new TransferInput
{
To = State.ProfitReceiver.Value,
Amount = amountForReceiver,
Symbol = input.Symbol
});
// For Token Holder Profit Scheme. (To distribute.)
State.TokenHolderContract.DistributeProfits.Send(new DistributeProfitsInput
{
SchemeManager = Context.Self
});
return new Empty();
}
public override ProfitConfig GetProfitConfig(Empty input)
{
return State.ProfitConfig.Value;
}
public override ProfitsMap GetProfitsAmount(Empty input)
{
var profitsMap = new ProfitsMap();
foreach (var symbol in State.ProfitConfig.Value.ProfitsTokenSymbolList)
{
var balance = State.TokenContract.GetBalance.Call(new GetBalanceInput
{
Owner = Context.Self,
Symbol = symbol
}).Balance;
profitsMap.Value[symbol] = balance;
}
return profitsMap;
}
测试¶
由于实现了ACS9的合约有一部分利润去往TokenHolder合约，还有一部分利润去往一个分红池，因此该测试中，需要一个TokenHolder合约的Stub，以及一个实现了ACS10的合约的Stub。相应地，在测试项目中，需要同时部署实现了ACS9的合约和实现了ACS10的合约。 在测试开始之前，可以通过实现一个IContractInitializationProvider接口，来初始化实现了ACS9接口的合约，将分红池合约名设置为另外一个实现了ACS10接口的合约：
public class ACS9DemoContractInitializationProvider : IContractInitializationProvider
{
public List<InitializeMethod> GetInitializeMethodList(byte[] contractCode)
{
return new List<InitializeMethod>
{
new InitializeMethod
{
MethodName = nameof(ACS9DemoContract.Initialize),
Params = new InitializeInput
{
ProfitReceiver = Address.FromPublicKey(SampleECKeyPairs.KeyPairs.Skip(3).First().PublicKey),
DividendPoolContractName = ACS10DemoSmartContractNameProvider.Name
}.ToByteString()
}
};
}
public Hash SystemSmartContractName { get; } = ACS9DemoSmartContractNameProvider.Name;
public string ContractCodeName { get; } = "AElf.Contracts.ACS9DemoContract";
}
准备一个用户账户：
protected List<ECKeyPair> UserKeyPairs => SampleECKeyPairs.KeyPairs.Skip(2).Take(3).ToList();
准备一些Stub：
var keyPair = UserKeyPairs[0];
var address = Address.FromPublicKey(keyPair.PublicKey);
// Prepare stubs.
var acs9DemoContractStub = GetACS9DemoContractStub(keyPair);
var acs10DemoContractStub = GetACS10DemoContractStub(keyPair);
var userTokenStub =
GetTester<TokenContractImplContainer.TokenContractImplStub>(TokenContractAddress, UserKeyPairs[0]);
var userTokenHolderStub =
GetTester<TokenHolderContractContainer.TokenHolderContractStub>(TokenHolderContractAddress,
UserKeyPairs[0]);
然后给用户转点ELF（TokenContractStub为初始bp的token合约的Stub，有很多ELF）：
// Transfer some ELFs to user.
await TokenContractStub.Transfer.SendAsync(new TransferInput
{
To = address,
Symbol = "ELF",
Amount = 1000_00000000
});
让该用户调用SignUp，检查是否得到了10个APP代币：
await acs9DemoContractStub.SignUp.SendAsync(new Empty());
// User has 10 APP tokens because of signing up.
(await GetFirstUserBalance("APP")).ShouldBe(10_00000000);
测试一下合约本身的充值方法：
var elfBalanceBefore = await GetFirstUserBalance("ELF");
// User has to Approve an amount of ELF tokens before deposit to the DApp.
await userTokenStub.Approve.SendAsync(new ApproveInput
{
Amount = 1000_00000000,
Spender = ACS9DemoContractAddress,
Symbol = "ELF"
});
await acs9DemoContractStub.Deposit.SendAsync(new DepositInput
{
Amount = 100_00000000
});
// Check the change of balance of ELF.
var elfBalanceAfter = await GetFirstUserBalance("ELF");
elfBalanceAfter.ShouldBe(elfBalanceBefore - 100_00000000);
// Now user has 110 APP tokens.
(await GetFirstUserBalance("APP")).ShouldBe(110_00000000);
用户通过TokenHolder合约锁仓57个APP，以便获取持币人分红合约中的利润：
// User lock some APP tokens for getting profits. (APP -57)
await userTokenHolderStub.RegisterForProfits.SendAsync(new RegisterForProfitsInput
{
SchemeManager = ACS9DemoContractAddress,
Amount = 57_00000000
});
调用10次Use方法，每次消耗0.3个APP，最终用户剩余50个APP：
await userTokenStub.Approve.SendAsync(new ApproveInput
{
Amount = long.MaxValue,
Spender = ACS9DemoContractAddress,
Symbol = "APP"
});
// User uses 10 times of this DApp. (APP -3)
for (var i = 0; i < 10; i++)
{
await acs9DemoContractStub.Use.SendAsync(new Record());
}
// Now user has 50 APP tokens.
(await GetFirstUserBalance("APP")).ShouldBe(50_00000000);
开发者使用TakeContractProfits方法，试图提取10个ELF作为利润，此时会在合约中自动分配该10个ELF：
const long baseBalance = 0;
{
var balance = await TokenContractStub.GetBalance.CallAsync(new GetBalanceInput
{
Owner = UserAddresses[1], Symbol = "ELF"
});
balance.Balance.ShouldBe(baseBalance);
}
// Profits receiver claim 10 ELF profits.
await acs9DemoContractStub.TakeContractProfits.SendAsync(new TakeContractProfitsInput
{
Symbol = "ELF",
Amount = 10_0000_0000
});
// Then profits receiver should have 9.9 ELF tokens.
{
var balance = await TokenContractStub.GetBalance.CallAsync(new GetBalanceInput
{
Owner = UserAddresses[1], Symbol = "ELF"
});
balance.Balance.ShouldBe(baseBalance + 9_9000_0000);
}
接下来检查利润分配结果。 分红池此时应该分配到了0.1个ELF：
// And Side Chain Dividends Pool should have 0.1 ELF tokens.
{
var scheme = await TokenHolderContractStub.GetScheme.CallAsync(ACS10DemoContractAddress);
var virtualAddress = await ProfitContractStub.GetSchemeAddress.CallAsync(new SchemePeriod
{
SchemeId = scheme.SchemeId,
Period = 0
});
var balance = await TokenContractStub.GetBalance.CallAsync(new GetBalanceInput
{
Owner = virtualAddress,
Symbol = "ELF"
});
balance.Balance.ShouldBe(1000_0000);
}
用户领取持币人分红方案中的利润，得到1个ELF：
// Help user to claim profits from token holder profit scheme.
await TokenHolderContractStub.ClaimProfits.SendAsync(new ClaimProfitsInput
{
Beneficiary = UserAddresses[0],
SchemeManager = ACS9DemoContractAddress,
});
// Profits should be 1 ELF.
(await GetFirstUserBalance("ELF")).ShouldBe(elfBalanceAfter + 1_0000_0000);
最后顺便测试一下合约本身的赎回方法：
// Withdraw
var beforeBalance =
await userTokenStub.GetBalance.CallAsync(new GetBalanceInput
{
Symbol = "APP",
Owner = UserAddresses[0]
});
var withDrawResult = await userTokenHolderStub.Withdraw.SendAsync(ACS9DemoContractAddress);
withDrawResult.TransactionResult.Status.ShouldBe(TransactionResultStatus.Mined);
var resultBalance = await userTokenStub.GetBalance.CallAsync(new GetBalanceInput
{
Symbol = "APP",
Owner = UserAddresses[0]
});
resultBalance.Balance.ShouldBe(beforeBalance.Balance + 57_00000000);