Introduction

Welcome! I am excited you have decided to learn more about the Angel Smart Treasury (AST) from Angel Protocol. This book aims to help new developers to understand the functionality and power offered by Angel Protocol’s smart contract platform so that they can quickly start building on top of us to deliver new and innovative financial solutions.

ELI5: What is the purpose of an AST?

An AST provides you with the tools to fund-raise, coordinate, and invest capital in a transparent and friction-less manner. ASTs connect donors and investors with non-profits, social enterprises and other change-makers around the world. It is a customizable, powerful, web3 infrastructure available in minutes!

Who should read this book?

In our humble opinion, everyone should read this book! 😉 That said, there are certain areas which will be more relevant to different readers.

If you are not technically inclined or you do not want or need to directly interact with the smart contracts and would prefer to use our provided web application for managing your AST, you should first read the Functional Documentation chapters to get a complete understanding of what Angel Protocol is, what the ASTs can do, and how to work with the existing Angel Protocol website UI.

If you are technically savvy and need to work with the smart contracts directly or you just want to dive deeper, then the Technical Documentation chapters are for you. These were written primarily with developers and tech-savvy users in mind. It will help if you come in with an understanding of how the Polygon blockchain (or a similar EVM-based blockchain such as Ethereum) and Solidity smart contracts work. We will be diving deeper into the technical aspects of how to use the Angel Protocol smart contracts directly here.

Regardless of the path you chose, there is a lot to learn in the coming pages that will help you better understand and use our platform. Stick with it and you might be surprised!

How to read this book?

Think of this book as a "Choose Your Own Adventure" format rather than a classic novel you need to read cover to cover.

This guide is written to provide explanations and details behind of ASTs and UI guides in our "Functional Documentation" sections. There we walk new users through how they can use our existing site to configure, launch, and manage their AST, all without a single line of code required!

In the "Technical Documentation" section of this book, we provide deeper explanations and breakdown the code behind ASTs using code snippets and contract interfaces that would be commonly encountered when using an AST programmatically. We have ordered the first sections to quickly orient users to the core logic and structures at play in the Angel Protocol contracts and Endowments that are important to understand first, we then dive into the AST creation process and the basics of using an AST multisig. With those foundations in place we build upon that, covering the various day-to-day scenarios that AST members can expect to encounter. Each section covers the overview of the setup, players and contracts involved, any important logic points or considerations. We will also look at relevant code snippets for the involved endpoints as well as any important structs as we go.

Typographical Conventions Used

Code Snippets

function testAllTheThings() {
    // some 1337 code here...
}

Important Points

⚠️ Heads Up: Important points will called out like this!

Technical Diagram Symbols Used

Symbol	Description
	Represents a smart contract on-chain. The "name" of the contract will always appear first in bold, along with an Address.
	Represents a single multisig contract transaction. These transactions are dependent on confirmation thresholds being reached to be executed.
	Represents an interactive endpoint on a smart contract. Messages always point at the blue receptor and outward flowing arrows represent downstream actions.
	Represents an EVM EOA wallet.
	Represents a critical decision step in the contract logic.
	This is money. 😄 It is used to represent the flow of tokens and resulting balances in a contract or wallet.

Overview

What You'll Learn:

• What Angel Protocol is and why you should use it
• Key Angel Protocol features
• Example use cases

What is Angel Protocol?

Angel Protocol provides fintech infrastructure that enables anyone to create & embed tokenized financial products in minutes with little to no coding required. When you build with us, you build on smart contracts that are executed on a blockchain network. This means that you don’t have to create and maintain accounts in the traditional financial system. We provide you with all the infrastructure and UI you need to interact in compliance with the financial system: fiat on/off-ramps, KYC, etc. These financial products are referred to as Angel Smart Treasuries and allow users to:

• Pool funds from around the world at low cost
• Invest in a carefully curated set of tokenized assets
• Make collective investment decisions
• Mint tokens for collective ownership and fundraising
• Improve transparency & trust

Users can further set a variety of parameters to program their AST with no additional coding required:

• Define how funds are locked
• Set contributors and beneficiaries
• Set a maturity date and associated logic
• Set who has permissions to execute actions
• Lock forever any of these parameters

You don't need to be a blockchain expert to utilize ASTs. Communicating with smart contracts is as easy as any traditional API integration. Create your API request and configure your financial product in only a few minutes. Use our open-source components for your UI:

• Wallet connect & drop-down
• Cross-chain deposits
• Registration flow & on-boarding for your clients
• Fully-fledged marketplace & user profiles
• Management dashboard

⚠️ Heads Up: We have some great technical documentation if you want to go deeper. Start with an Angel Protocol Smart Contracts.

With Angel Protocol you can build or embed the ability to invest in tokenized assets & yield, coordinate using decentralized governance, and program trust-less execution in less than 60 minutes. We combine the best of tokenized infrastructure in one powerful but simple product, providing all the benefits of Web3 while abstracting away the complexity.

Why use Angel Protocol?

The tokenization of assets is both revolutionary and inevitable. Significant value, efficiency, and democratization of access are unlocked with the move from traditional to tokenized assets (along with new blue oceans of possibility through programmable, trust-less execution). Those who embrace and leverage this technology gain a significant competitive advantage. However, building customized financial products is out of reach for most businesses and individuals:

• Regulation & Intermediaries: Time-to-market often takes anywhere from 2 to 6 months, or longer if not utilizing a Banking-as-a-Service (BaaS) provider
• Development Cost: Minimum development cost for a new financial product can easily exceed $150K for simple functionality
• Cumbersome: It can take >1,000 lines of code required to tie together multiple API providers to make a product

Angel Protocol’s infrastructure makes customized financial products available for all, with no friction:

• Fast: It takes <60 min to configure and launch a 100% bespoke financial product
• Cheap: No upfront fees or subscriptions mean you can launch your product for free
• Convenient: Programmable infrastructure with an open-source UI so you only need to deal with 1 solution

We do the heavy lifting for you, carefully researching, selecting, and assessing the risk of assets available for investment. We continuously vet and integrate third-party tools that support the operations of decentralized organizations (payroll, accounting, project management, etc.)

Revenue Sharing

A unique feature of our infrastructure is you actually get paid to build on Angel Protocol, enjoying a 20% revenue share from all financial products you create. You will automatically receive your share of all fees generated by those financial products that are created with your referrer address in the API request. Further, a portion of all Angel Protocol fees get redirected to social impact. You win, your customers win, and the world wins. You no longer need to invest significant time and resources to build the financial products your customers deserve. Take ownership into your own hands with the power and simplicity of Angel Protocol’s infrastructure.

Cost-leading Pricing Model

We believe in democratizing access to financial opportunity regardless of a person’s wealth or location. Thus, we charge no setup costs, take no cut of incoming contributions, and have no subscription fees. We only win when our customers win, charging 1% on balances (per annum) and 1.5% on withdrawals (of funds leaving Angel Protocol). Simple, transparent, and inclusive. We plan to introduce a premium service in the future for those seeking a dedicated account manager, white-glove help desk, technical assistance for integration, and help with admin/legal. Currently, the cost is free: talk to us.

Who uses Angel Protocol?

Angel Protocol’s infrastructure is trusted by over 170 organizations around the world and can be utilized for a variety of different use cases related to raising, investing, and coordinating funds. Some examples include:

• Nonprofit endowment accounts & fundraising marketplace
• Emerging market crowdfunding
• Micro-lending (e.g. agricultural microloans in Myanmar)
• Family, education, and charitable estate planning trusts
• Impact funds (collective fundraising, investment, and grant-making)

Angel Smart Treasuries are available for any business, organization, or individual who would like to benefit from them. For a more detailed overview of existing & potential use cases, please see Examples And Use Cases.

Why we build

What You'll Learn:

• Angel Protocol’s foundation: Social impact
• Impact case studies
• Our Vision, Mission & Values

Rooted in Social Impact

We are a decentralized organization rooted in social impact. Decentralized, because the protocol is run and maintained by its token holders. Rooted in social impact, because the protocol is designed to support nonprofit and social impact organizations. Angel Giving lit the spark of Angel Protocol, bringing our team together with a passion to change the world for the better. Its purpose is to provide free access to non-custodial on-chain endowments for nonprofits around the world, leveling the playing field and providing a path to financial stability regardless of the organization’s size or location. But we wanted to go further. Angel Protocol’s infrastructure is carefully designed to benefit the nonprofit organizations of Angel Giving. A portion of all protocol fees are redirected to nonprofits on Angel Giving, which means anytime you use Angel Protocol’s infrastructure you’re also funding local change-makers working to improve the world. Win and help win.

Impact Case Studies

We’ve been able to raise over $6M in donations for nonprofits through the generosity of our donors and partners. Some examples of those impact stories are captured below:

• $1.5M raised for climate change through an NFT gamified fundraising campaign (link)
• $500K sent to a local Philippines NPO for disaster relief (link)
• $200K raised for Ukrainian refugees (link)
• School built in Uganda through dedicated NFT mint (link)

To stay up to date on our social impact efforts, please check out Angel Giving and join their newsletter.

Vision, Mission, and Values

Angel Protocol's vision is to create the world's leading infrastructure for global, equitable access to financial opportunity. To accomplish that vision, our current mission is to democratize access to financial opportunity by enabling organizations and individuals to leverage the benefits of web3 technology.

Our core values guide us in driving forward our vision & mission:

1. Impact First: All of our decisions further our ability to create a positive impact on the world
2. Equity: Everyone deserves free access to financial opportunity, and everyone deserves a voice
3. Win and Help Win: We always seek positive-sum outcomes and believe greater impact can be generated by aligning incentives so everyone wins
4. High Say/Do Ratio: We follow through on our declared intent with matching actions to build trust
5. Mindful Intentionality: We measure twice and cut once. We believe thoughtfulness leads to actions that are true, kind, and necessary

Getting Started

What You'll Learn:

• How to setup your first AST with the Angel Protocol Launchpad
• How to use the various parts of your AST in the Angel Protocol Admin area
• How to configure your AST in the Angel Protocol Admin area

Creating Your Angel Smart Treasury

What You'll Learn:

• How to setup your wallet
• How to create your AST
• Setup options

Step 1: Wallet Creation

You will need a tokenized asset wallet to interact with your AST. Already have a wallet for tokenized assets? Great, you are all set! Skip to the next section. New to tokenized assets? No problem! You can quickly and easily set up your wallet with simply an email address using Web3Auth wallet.

Step 2: About

Once you have your wallet setup, you are ready to begin creating your AST. In this section you can provide basic information like name and brief description/tagline.

Step 3: AST Management Settings

Next you can setup the management of your AST. This determines your AST’s voting parameters and voting members. You must weigh security against operational efficiency when determining how many members are required to pass a vote (more members = more security, fewer members = more operational efficiency).

In the first section, you choose your AST members. In the second section, you choose the minimum required participation level, proposal duration, and whether proposals execute automatically once quorum is reached.

Step 4: Whitelists (optional)

In this section you can choose who is able to deposit (contributors) or withdraw (beneficiaries) from your AST. You are not required to limit contributors or add beneficiaries, and you may change this at any time.

Whitelisting Contributors

Whitelisting Withdrawals

Step 5: Maturity

If you’d like to set a maturity date/action for your AST, you may do so here. This is useful for any situation where you would like to release access of funds to specific beneficiaries at a specific time, such as when setting up trusts. It can also be used as a recovery fail-safe by setting up a separate recovery wallet as the beneficiary at a future date.

Step 6: Split of Contribution

There may be situations where you would like AST funds split between locked (principal protected) & liquid (available) accounts. By default, contributors to your AST can choose how their contribution is split between these locked & liquid accounts. You may choose to modify that option here by setting default and minimum/maximum ranges, or deactivate it altogether.

Step 7: Fees

In addition to our standard fees, you may choose to add additional fees on top. Fees can be applied to withdrawals, deposits, and/or on balances (i.e., AUM fees).

Step 8: Summary

The final step before finishing creating your AST is reviewing the summary of settings prior to confirming.

Step 9: Success!

Congratulations! You have successfully set up your AST & it is ready immediately for use.

Using Your Angel Smart Treasury

What You'll Learn:

• Understanding of AST dashboard view
• Basics of using your new AST (Deposit/Withdrawal, Buy/Sell, Contributions, Maturity)

AST Dashboard

Your AST dashboard provides an overview of your total account balances and recent contributions. The left-hand menu allows you to easily navigate to relevant sections. We will begin by going over some basics before diving deeper into specific functionality.

Deposit / Withdrawal

Deposit

Funding your AST is easy, whether transferring in existing tokenized assets or depositing from your bank or card. We utilize a network of on-ramp partners covering broad geographies. This section will allow you to deposit funds to be utilized for trading, investment, or simply non-custodial storage.

Withdrawal

Withdrawals from your AST Liquid balance can be done at any time, pending a confirmation vote from your AST multisig's managing wallets. Simply select the currency & account you’d like to withdraw from, then choose the destination network & wallet.

The ability to withdraw directly to your bank account is being added soon!

Buy / Sell

In this section you can buy & sell tokenized assets from your AST tokens on hand balances. To start this will allow us access to any approved tokens on UniSwap Protocol. We have plans expand this across all major blockchains thanks to our interchain partners Squid & Router Protocol!

Contributions

This is where you can view all contributions into your AST and download, export, or filter contribution history.

Maturity

If you’ve chosen to set up maturity for your AST, you can configure options here by adding/removing beneficiaries, updating allowance splits, or changing the maturity date.

Configuring Your Angel Smart Treasury

What You'll Learn:

• How to manage your AST (Decision Center & Whitelists)
• Updating settings (Admin Wallet, Donor Verification & Permission)

Decision Center

The decision center is where all requests must be voted on to be approved or rejected. You can expand requests to see additional details, then simply click the approve or reject icon accordingly. Requests may include updating AST settings or taking various actions within the AST, such as making investments or updating the profile. You will be asked to confirm before proceeding.

Whitelists

If you’d like to review or update contributor or beneficiary whitelist settings, you may do so here. Adding or removing contributors and beneficiaries is as easy as clicking the relevant icon to remove or add:

Allowances

You may also add, update, or remove allowances here.

When adding or updating, you can select the relevant currency for the allowance.

Adding Allowances

Updating Allowances

Admin Wallet

The Admin Wallet controls your AST and is comprised of the members you’ve selected. You can add and remove members here along with changing their voting weight. You can also adjust settings related to the proposal process such as # of members required to vote, duration, and auto-execution toggle.

Donor Verification

If your AST is operating as a nonprofit or DAF you may choose to toggle donor verification on or off in this section.

Permissions

This is where you can update who has permission to change or access different aspects of your AST. You can toggle between Admin Wallet or Delegate Wallets, and update delegates. You may also lock settings permanently.

⚠️ Warning: Locking settings permanently is irreversible!

Functionality

What You'll Learn:

• How to make Investments to/from Angel Protocol Strategies from your AST in the Angel Protocol AST Admin area
• Modifying and updating your AST Profile (coming soon!)
• Governance of you AST (coming soon!)

Investments

Invest Dashboard

The invest dashboard lets you see your current account balances along with investment options. You can drill into details around the liquid & locked accounts, select investments, and toggle expert mode to see a complete list of investment opportunities.

Locked & Liquid Accounts

The Liquid & Locked account details will allow you to see your specific balances, performance history, and investment positions.

Transferring

You can transfer funds from the Liquid to the Locked account by selecting VIEW ALL in your Liquid Account Free Balances Overview and then choosing TRANSFER ASSETS.

Investing into a Strategy

When you click INVEST on a strategy, you will be able to see more details about the investment and choose the account to invest from:

You will be prompted to confirm before executing the transaction.

Redeeming from a Strategy

To redeem your investments, simply navigate to the Liquid or Locked account and click REDEEM on the strategy you are ready to exit.

Examples and Use Cases

Functionality Examples

Simple Multisig

The default setup for AST on creation is a multisig (i.e. Admin Wallet). This is the simplest form of an AST. At any time, the owners of ASTs can opt-in for tokenized governance with either an existing token or by creating a new token. At the moment of the opt-in, the owners can decide which parameters of the AST fall under the governance and which are still controlled by the native multi-sig.

Existing Token

When the owners of an AST decide to opt-in for DAO governance using an existing token, a governance contract is instantiated that allows token holders to vote on the parameters that have been chosen by the contract owner.

Eligible tokens are pre-approved by the AP DAO along with a designated AMM token pair contract address that is used to convert fees from the AST (generally denominated in stablecoins) into the token in use for distribution to stakers as rewards.

The owners of an AST can instantiate a Matching contract that contains a reserve of tokens that are distributed to contributors following a set of rules defined by the governance of the AST.

A Rewards contract can also be instantiated that enables using a reserve of tokens to increase staking rewards.

New Token Setup

Fixed Supply

Bonding Curve

Simple Personal Endowment

Charitable Estate Planning Trust

Employee Pension Plan

Social Impact Fund

Lossless Impact Group

Social Impact Collective

Current Customer Examples

Here we will highlight several of the current customers and the different ways they are utilizing Angel Protocol ASTs.

Angel Giving

https://angelgiving.io/

About

Angel Giving provides nonprofits across the world with free access to their own endowment and a marketing page on a global charity marketplace. Donations are directed to a NPO’s AST account and automatically invested in low-risk, high-yielding products made possible by blockchain technologies. Every week, a portion of the interest from those DeFi products is sent to the charity and the remainder is automatically reinvested, compounding in perpetuity to provide sustainable funding. Angel Giving is a global team of individuals with backgrounds in philanthropy and technology, passionate about building a world where humanity is empowered with the financial security to solve our grand challenges. Their incredible community raised over $6 million dollars in donations to more than 160 charities, with $1.5M raised to fight climate change, $500k in humanitarian relief for those impacted by Typhoon Rai, and over $200k to support Ukrainian refugees.

Goals

• Democratize access to financial opportunity for nonprofits so they can enjoy financial sustainability regardless of their size, resources, or location
• Ensure all nonprofits have access to a free fundraising profile and embeddable donation widget on their site
• Promote charitable giving on-chain and connect giving partners to beneficiary NPOs
• Provide donors access to on-chain DAFs to donate and manage tokenized assets

Parameters

Angel Giving integrates AST functionality directly into their front end and utilizes a registration process to onboard NPOs. That registration process allows NPOs to create pre-configured ASTs designed to work as endowments, and generates a fundraising marketplace page where the NPO can be discovered on Angel Giving’s marketplace. The marketplace front end is open-sourced and available to leverage for the creation of similar or modified products. Below are the pre-configured and adjustable parameters for NPOs:

Admin Wallet: Default multisig created for each NPO initially using the registration wallet

Admin Settings: Set by NPO

Locked and Liquid Settings: Chosen by donor on marketplace (defaulted to 100% locked), or chosen by NPO during widget creation

Fees: No additional fees added, Angel Giving seeks to be a cost leader to be an inclusive as possible for financially strained NPOs

Donor Verification: Set by NPO

Investments: A preset plan is devised to automatically send 75% of yield generated within Locked funds to Liquid

Tun Yat

About

Tun Yat provides credit facilities for smallholder farmers with limited financing options in Myanmar. Servicing over 5,000 farmers to date Tun Yat is seeking to transparently scale their loan portfolio with the utmost capital efficiency.

Goals

• Pool funds from around the world given local political and economic challenges
• Remove middlemen by building on-chain farmer credit profiles to directly connect farmers to funders
• Invest in curated tokenized assets to cover ongoing OPEX costs
• Pilot smart-contract based decisions with auto execution of loan decisions

Parameters

Admin Wallet: Multi-sig set up consisting of three members from Tun Yat’s headquarters. Each will have equal voting weight. In the future, Village Committees receiving loans will be given admin wallet access and an equal vote for ongoing funding decisions.

Admin Settings: 66% (2/3) vote for execution, 72 hours for voting window, and auto execution on.

Whitelists:

• Contributors: ‘Anyone’ can fund Tun Yat’s AST
• Beneficiaries: Vetted Village Committees are the only participants eligible to receive funds from Tun Yat, plus an additional Tun Yat OPEX wallet to maintain clarity in financial flows

Maturity: Every six months, 20% of Locked funds go to OPEX wallet. This enables a sustainable business model as yield will help offset ongoing OPEX costs.

Locked and Liquid Settings: Default is set to 75% Liquid to fund ongoing agricultural microloans, but donors can customize this to their preferences.

Fees: No additional fees will be charged as Tun Yat is not passing any additional costs to their farmer clients

Donor Verification: Off, no KYC required for funding Tun Yat’s AST

Permissions: Tun Yat will keep all settings unlocked as they become more comfortable with the dynamics of ASTs. Delegate will have access to change Tun Yat’s profile but all other decisions will be in control of the Admin wallet.

Investments: A preset plan is devised to automatically send 50% of yield generated within Locked funds to Liquid. Additionally, any funds donated to the Locked account will auto invest into a stablecoin pool to maximize risk reward for sustained funding.

Nibi

About

Nibi is a tech platform supporting over 250 grassroots Colombian nonprofits with marketing, fundraising, and capacity building. Nibi seeks to build trust in the burgeoning CSR space in LATAM while also opening up financial rails to seamlessly accept global donations.

Goals

• Implement a smooth front-end API to increase donor and funder access globally in fiat and cryptocurrency
• Transparently manage global donations for their respective clients
• Demonstrate the benefits of an endowment for their grassroots nonprofit clients

Parameters

Admin Wallet: Multi-sig set up consisting of four members from Nibi’s team. Each will have equal voting weight. Nibi will be the sole holder of all keys within the AST, as they will manage all financials for their clients.

Admin Settings: 75% (3/4) vote for execution, 72 hours for voting window, and auto execution on.

Whitelists:

• Contributors: ‘Anyone’ can fund Nibi’s AST
• Beneficiaries: Mirror of the admin wallet multi-sig holders. As Nibi’s clients are grassroots nonprofits with limited access to technology, Nibi will act as the custodian on their behalf managing all financial flows.

Maturity: None. Nibi will manage financial flows on an ad-hoc basis, immediately sending donations for their respective receiving client.

Fees: 2%. Nibi manages donor engagement and increases the amount of funds for their clients, for this they will administer a 2% fee on all funds managed. This is in addition to the 20% of revenue Nibi will share from base Angel Protocol fees.

Donor Verification: On, Donor Verification will be required for funding Nibi’s AST. This enables Nibi to manage and strengthen donor relationships.

Permissions: Nibi will lock forever a majority of their parameters. Delegate will have access to change Nibi’s profile, but all other decisions will be in control of the Admin wallet.

Investments: A preset plan is devised to automatically send 75% of yield generated on Locked funds to Liquid. Additionally any funds donated to the Locked account will auto invest into a stablecoin pool to maximize risk reward for sustained funding.

SOWE

About

SOWE and their field partner Yamba Hearts for Uganda empower women to start their own businesses with zero interest loans provided by global donors. SOWE seeks to remove any intermediaries in directly funding women entrepreneurs while also establishing an evergreen fund to offset any loan defaults.

Goals

• Pool funds from around the world to support local entrepreneurs
• Embed transparency in loan origination and repayment
• Create a robust evergreen fund with the automated Investment and Locked features

Parameters

Admin Wallet: Multi-sig set up consisting of three members from SOWE’s team and two members from Yamba Hearts for Uganda. As the Yamba Hearts for Uganda team works directly with the loan applicants, their vote will be weighted 2:1 compared to SOWE’s team.

Admin Settings: Approximately 57% (4/7) vote for execution, 72 hours for voting window, and auto execution on.

Whitelists:

• Contributors: ‘Anyone’ can fund SOWE’s AST
• Beneficiaries: This will be expanded on a rolling basis. The Admin wallet team will help loan recipients with wallet set-up and for each approved loan, a new beneficiary will be added to the whitelist.

Maturity: None. SOWE will manage loans on a rolling basis. In the future, rewards for repaying loans on-time could receive a programmed bonus at maturity of loan cycle.

Locked and Liquid Settings: Default is set to 75% Liquid. This allows for 25% to continue to generate yield to off-set any risk of loan default.

Fees: 1%. SOWE will charge a 1% fee to support their ongoing operational costs. This is in addition to the 20% of revenue SOWE will share from base Angel Protocol fees.

Donor Verification: Off, KYC will not be required to support women entrepreneurs in Uganda.

Permissions: SOWE will experiment with locking a few features while keeping a majority flexible as they gain familiarity with the platform.

Investments: A preset plan is devised to automatically send 25% of yield generated on Locked funds to Liquid. SOWE would like to build a robust evergreen fund and will keep a majority of Locked funds within the Locked account for emergency use. Additionally any funds donated to the Locked account will auto invest into a stablecoin pool to maximize risk reward for sustained funding.

Angel Protocol Smart Contracts

What You'll Learn:

• The different "types" of Endowments
• Balances and Accounting with Endowments
• How funds flow in Angel Protocol

Overview of Key Smart Contracts

There are two important smart contracts that you must be aware of as a developer looking to understand the Angel Protocol ecosystem. These are:

• Registrar Contract
• Accounts Contract

We will cover each of them in turn in the next sections.

Registrar Contract

This contract serves as THE source of truth for all other Angel Protocol contracts on a given blockchain. It holds a large number of values in its storage struct that most other contracts will query to get the correct values for their own operations. It is owned and controlled by the Angel Protocol Team’s Admin multisig contract. Only this multisig can modify this contracts values.

The full config struct of the Registrar contract (as returned from a query to the getConfig endpoint):

struct Config {
    address owner; // AP TEAM MULTISIG
    address applicationsReview;
    address indexFundContract;
    address accountsContract;
    address treasury;
    address subdaoGovCode;
    address subdaoCw20TokenCode;
    address subdaoBondingTokenCode;
    address subdaoCw900Code;
    address subdaoDistributorCode;
    address subdaoEmitter;
    address donationMatchCode;
    address donationMatchCharitesContract;
    address donationMatchEmitter;
    AngelCoreStruct.SplitDetails splitToLiquid;
    address haloToken;
    address haloTokenLpContract;
    address govContract;
    address collectorAddr;
    uint256 collectorShare;
    address charitySharesContract;
    AngelCoreStruct.AcceptedTokens acceptedTokens;
    address fundraisingContract;
    AngelCoreStruct.RebalanceDetails rebalance;
    address swapsRouter;
    address multisigFactory;
    address multisigEmitter;
    address charityProposal;
    address lockedWithdrawal;
    address proxyAdmin;
    address usdcAddress;
    address wethAddress;
    address cw900lvAddress;
}

Aside from managing the various contract addresses and wallet variables, the Registrar is also responsible for the curation of approved “Strategies” (ie. What ASTs invest their funds into) and “Network Information” about other external chains that Angel Protocol has Strategy Vaults deployed on. The last important thing the Registrar handles is the management of the protocol level “Fees” that can be setup and applied when Endowments take certain actions like withdrawing funds from the protocol or when a harvest of Strategy vaults takes place.

Overall, the Registrar contract is a critically important contract to be aware of as you’re reading and understanding the code. It is everywhere, and yet it is not a contract you will ever really need to interact with directly.

Accounts Contract (Diamond)

This diamond contract is where all of the core business logic that governs all ASTs lives. If you are unfamiliar with what a Diamond is please stop and read over the EIP-2535 specification to get an understanding and then come back here. Don’t worry we will wait! :) Everything else beyond this point will make a lot more sense after that.

The Accounts contract is responsible for:

• Tracking all existing Endowment accounts in the Angel Protocol ecosystem, their current status, and their configuration settings
• Managing the internal ledger for all Endowment balances
• Correctly applying logic for inbound deposits and outbound withdraws
• Providing the infrastructure to allow Endowment owners to make investments and redemptions to/from any Angel Protocol Strategy vaults, whether those are on the same chain or a different chain entirely
• Allow Endowment owners the ability to update their Configuration settings and manage things like permissions and control over changing various parameters

The other important concepts to wrap your head around, before we dive deeper into the code, is the distinction between the different types of Endowments, as well as the internal, accounting setup for all Endowment balances.

Types of Endowments

Angel Protocol has two types of Endowments at the smart contract level: Charity Endowments & Normal Endowments. The internal representation for an EndowmentType in the contracts is an enum:

enum EndowmentType {
    Charity,
    Normal,
    None
}

Charity Endowments are specialized Endowments reserved only for vetted and verified Non-Profit Organizations. These are outside the scope of this guide, but it is important to know they exist for when you see them mentioned throughout the logic in the smart contracts codebase. Normal Endowments are ASTs. So when you see references to “Normal” Endowments in the codebase, just think AST and you will be okay. We will use AST throughout this guide to avoid any confusion. AST Endowments have far greater flexibility with regards to their configuration options and their management capabilities. They are the v2 of the Charity Endowments.

Endowment Balance Accounting

Regardless of their Type, all Endowments recorded in the Accounts contract have a Locked Account and an Liquid Account balance. Internally in the contracts this is represented by an enum AccountType:

enum AccountType {
    Locked,
    Liquid,
    None
}

The Locked portion represents the balance that is...well locked and cannot be withdrawn. It is helpful to think of this as the “endowment” portion of your account, the part that is set aside to be invested and grow un-distributed. The Liquid portion can be thought of like a current (or checking) bank account where there are little to no restriction on how much, to whom, or when money can be taken out of it.

Fund flows into, around, and out of Angel Protocol

All funds enter Angel Protocol via deposits into an Endowment’s un-invested “bucket” of funds, which we refer to in the contracts as “tokens-on-hand”. Theses buckets exist in a locked and liquid version. All investments and redemptions are carried out from and return back to the respective tokens-on-hand bucket from which they originated. All AST withdraws are pulled from the Liquid tokens-on-hand bucket only.

For invested locked funds, harvest events are where a certain percentage of the earnings generated by those funds are unlocked and moved into the liquid-version of the same strategy, freeing them up to be redeemed to a liquid tokens-on-hand bucket and withdraw if desired. This is how Angel Protocol Endowments throw off an income stream for ASTs.

Getting Started With ASTs

What You'll Learn:

• Creating an AST directly on-chain
• Basics of AST multisigs
• How to manage the members of an AST multisig

Creating An AST

Any user who wishes to do so may create an AST. To do so you must use the createEndowment function on the Accounts diamond contract facet “AccountsCreateEndowment”. This endpoint expects an extensive configuration message that lays out all of the settings and parameters for the new AST. We will cover the function itself and the logic the message arguments and what they are for.

The createEndowment function payload on the Accounts contract facet AccountsCreateEndowment expects a single argument struct like so:

struct CreateEndowmentRequest {
        address owner;
        bool withdrawBeforeMaturity;
        uint256 maturityTime;
        string name;
        AngelCoreStruct.Categories categories;
        uint256 tier;
        AngelCoreStruct.EndowmentType endow_type;
        string logo;
        string image;
        address[] cw4_members;
        bool kycDonorsOnly;
        AngelCoreStruct.Threshold cw3Threshold;
        AngelCoreStruct.Duration cw3MaxVotingPeriod;
        address[] whitelistedBeneficiaries;
        address[] whitelistedContributors;
        uint256 splitMax;
        uint256 splitMin;
        uint256 splitDefault;
        AngelCoreStruct.EndowmentFee earningsFee;
        AngelCoreStruct.EndowmentFee withdrawFee;
        AngelCoreStruct.EndowmentFee depositFee;
        AngelCoreStruct.EndowmentFee aumFee;
        AngelCoreStruct.DaoSetup dao;
        bool createDao;
        uint256 proposalLink;
        AngelCoreStruct.SettingsController settingsController;
        uint256 parent;
        address[] maturityWhitelist;
        bool ignoreUserSplits;
        AngelCoreStruct.SplitDetails splitToLiquid;
    }

We will breakdown what each of these arguments is used for, grouped by their area of application, and also how different choices for these will impact the created AST in terms of functionality.

Creation Message Arguments

Endowment Owner

address owner; This field should usually be set as the message sender EOA, as it will only be used temporarily until the AST Multisig is created and set as the true owner.

Endowment Type

AngelCoreStruct.EndowmentType endow_type; This field expects and EndowmentType enum:

enum EndowmentType {
        Charity,
        Normal,
        None
    }

It should always be set as "Normal" for AST creation message.

Endowment Tier

uint256 tier; This field should always be set as 0 for AST creation messages. This field is used exclusively by Charity endowments.

Maturity Time

bool withdrawBeforeMaturity;
uint256 maturityTime;

These fields are responsible for controlling when the AST Endowment will mature at and whether or not withdraws are possible before this maturity date. Both of these fields can only be set at the time of instantiation.

If withdrawBeforeMaturity == true, then funds will be be able to be withdrawn before the maturity date, if set to false, then funds are locked until maturity is set (if ever).

The maturityTime field, if non-zero, sets the time that the Endowment will mature at. If 0 the endowment effectively has no maturity date (indefinite).

Categories and UN SDGs

AngelCoreStruct.Categories categories; This field expects a Categories struct which lays out the UN SDGs and General categories that apply to an Endowment:

struct Categories {
    uint256[] sdgs;
    uint256[] general;
}

SDGs are used mostly with Charity endowments only, though they could be used by an AST if desired, though having at least 1 SDG set is not a requirement for them, unlike with Charity endowments. General categories is a open, flexible system thin which AST owners can set integer values on chain for internally defined categories. This General category might be useful for users that have many ASTs or those that have my sub-AST (child ASTs) that want to group them by internal classifiers.

Basic Endowment Info Strings

string name;
string logo;
string image;

These fields are simple, informational string values that will help identify your AST endowment on-chain and can be used by those who are not using supplemental database storage for AST information.

• Name: The name of your AST
• Logo: A URL string that points to your AST’s logo image
• Image: A URL string that points to your AST’s banner/supplemental image

KYC Required

bool kycDonorsOnly; If set to true, the AST is stating its preference for only receiving funds from KYC’d donors/contributors. This is something that would be read by and enforced from the front-end environment, as there is currently no real way to do this on-chain today.

MultiSig Initial Configs

address[] cw4_members;
AngelCoreStruct.Threshold cw3Threshold;
AngelCoreStruct.Duration cw3MaxVotingPeriod;

The above argments control the starting vaules for the AST Endowment’s MultiSig.

• cw4_members: A list of EVM addresses that should be setup as the starting owners/members of the AST Endowment multisig
• cw3Threshold: This argument expects a Threshold struct which lays out the following:

struct Threshold {
    ThresholdEnum enumData;
    ThresholdData data;
}

ThresholdEnum struct specifies the type of threshold used:

enum ThresholdEnum {
    AbsoluteCount,
    AbsolutePercentage,
    ThresholdQuorum
}

ThresholdData struct is where the relevent values for the above threshold type are passed. When not applicable, a 0 value can be passed:

struct ThresholdData {
    uint256 weight;
    uint256 percentage;
    uint256 threshold;
    uint256 quorum;
}

Whitelists

address[] whitelistedBeneficiaries;
address[] whitelistedContributors;
address[] maturityWhitelist;

These values setup the allow lists for what restrictions, if any, will exist for those wallets that will be beneficiaries of or contributors to the AST. If an empty array is passed it is assumed that there should be NO restrictions on that field (ie. Any wallet address will be allowed). The maturityWhitelist field is the set of addresses that can access the AST funds at the time of maturity. It is distinct from the other two whitelists here, which apply only while the AST is not yet mature.

Split Logic

uint256 splitMax;
uint256 splitMin;
uint256 splitDefault;
bool ignoreUserSplits;
AngelCoreStruct.SplitDetails splitToLiquid;

???

Custom Fees

AngelCoreStruct.EndowmentFee earningsFee;
AngelCoreStruct.EndowmentFee withdrawFee;
AngelCoreStruct.EndowmentFee depositFee;
AngelCoreStruct.EndowmentFee aumFee;

???

Settings Controller

AngelCoreStruct.SettingsController settingsController; This field expects a SettingsController struct which lays out on-chain enforced rules as to whom can make changes to which AST endowment fields and settings:

struct SettingsController {
    SettingsPermission endowmentController;
    SettingsPermission strategies;
    SettingsPermission whitelistedBeneficiaries;
    SettingsPermission whitelistedContributors;
    SettingsPermission maturityWhitelist;
    SettingsPermission maturityTime;
    SettingsPermission profile;
    SettingsPermission earningsFee;
    SettingsPermission withdrawFee;
    SettingsPermission depositFee;
    SettingsPermission aumFee;
    SettingsPermission kycDonorsOnly;
    SettingsPermission name;
    SettingsPermission image;
    SettingsPermission logo;
    SettingsPermission categories;
    SettingsPermission splitToLiquid;
    SettingsPermission ignoreUserSplits;
}

As you can see from the struct shape and contents, the SettingsController struct is a set of fields which hold SettingsPermissions struct with have all the relevent permissions details encoded:

struct SettingsPermission {
    bool ownerControlled;
    bool govControlled;
    bool modifiableAfterInit;
    Delegate delegate;
}

Parent / Child Endowments

uint256 parent; If you have an existing AST Endowment that will be the parent/owner of a sub-AST or child AST Endowment, this field is where that parent AST Endowment ID should be placed. The time of creation is the only opportunity at the present time where this field can be set. If no parent is needed, as will be the case for most AST users, simply pass a 0 value here.

AST Multsigs

Multisig contracts are commonplace in web3. They allow groups of users (the owners or members as they are often referred to as) to do things like approve transactions of shared assets held by their multisig contract and in general allow for better security of funds and addresses replacing users when they lose access to or have their signing wallet compromised. There a many different implementations of multisig contracts, but they usually share core similarities.

Multisig Transactions

A transaction must collect signatures of approval from the members of the multisig. Just like in the "real-world", where voter petitions to a governing body need to have some thousands of signatures before it can be read before parliament, so too must a multisig transaction collect certain a number of signatures from its owners. The number of signatures that is required for a proposed transaction to have before it can be executed on-chain is called the threshold.

Once a transaction has collected signatures above the threshold, it can be executed by any valid wallet address on-chain. Execution is not limited to the member addresses themselves, which is useful when it comes to other contracts or scripts being able to execute transactions.

Want to go deeper?

If you are interested in learning more about multisig contracts in depth we can recommend the following articles and resources for additional reading:

• What Is a Multisig Wallet? (Coindesk) is a beginner friendly overview of multisig contracts
• Multisig Contracts in Ethereum (Medium) is a more advanced overview of multisig contracts in EMVs using Solidity with discussions around on-chain vs off-chain signing of transactions

How Does a Multisig Work?

All actions taking place with a multisig follow the same flow:

1. Propose a transaction
2. Achieve a passing level threshold of confirmations
3. Execute the proposed transaction to the destination contract

Submitting a transaction

Everything starts with a multisig member submitting a transaction for consideration for execution by the other members of a multisig. The output of a successful submission would be the resulting transaction ID.

⚠️ NOTE: Take care to record this returned Endowment ID! It will be important for all members to interact with and sign a transaction and to lookup the status of a transaction.

This message and args would look something like:

submitTransaction("A short title", "description of the proposed transaction", "0x..1003", 0, <withdraw msg as binary>)

Confirming a transaction

In order to confirm a pending multisig transaction members of the multisig must confirm the transaction. Members have several options available to them with regards to exercising their voting powers on a multisig contract for which they must submit the following messages, each time passing the transaction ID along as the sole argument:

Confirm a Transaction (approval vote for execution)

confirmTransaction(uint256 transactionId)

Revoke a confirmation (rescind a confirmation previously submitted for a transaction)

revokeConfirmation(uint256 transactionId)

Once a transaction has acquired enough confirmations to meet the passing threshold level set it is ready for the final step: Execution!

Executing a passing transaction

The hard work of gathering consensus among multisig members for a proposed transaction has been carried out. Now the time has come to execute the transaction. This requires a single submission, which can be submitted by any valid EOA wallet, and will pass so long as:

1. The threshold for a transaction has been met
2. The data payload is valid and does not cause downstream errors that would cause the transaction to fail.

The execution message is very simple and looks like this: executeTransaction(uint256 transactionId)

Managing The Members Of A Multisig

Managing internal affairs of an AST multisig is the same process as any other transaction. The only difference is really that the destination is set as the multisig contract itself. This sort of setup is used for many common tasks such as:

• Adding a new member (owner) addOwner(address owner)

• Removing a member (owner) removeOwner(address owner)

• Replacing an existing member (owner) with a new one. This is useful for when an existing member loses access to their wallet or has it compromised and needs to change to a new wallet. replaceOwner(address owner, address newOwner)

Advanced AST Functionality

What You'll Learn:

• Handling deposits into your AST
• Creating a withdrawal from your AST

Getting Funds Into And Out Of An AST

Now that we've covered setting up your AST, it's time to get into the important stuff. The money!

In order to be useful, ASTs need to be able to receive funds from the outside world. We refer to these as deposits on the contracts. Deposits are open to the world by default, but can be restricted to a specific whitelisted set of contributor addresses, if so desired.

Inversely, ASTs need to send money out into the world from it's pool of tokens held on hand in their Liquid balances. This could be for things like paying a supplier for services, paying employees salaries, or many other things. Like deposits, withdraws are set to be capable of being sent to any address, though like with deposits we've added logic to allow this to be restricted to a finite list of beneficiaries.

Taking Deposits/Contributions

This is accomplished with the send of a valid deposit message to the Accounts contract any wallet. We will assume there are no restrictions on the wallets that can interact with the deposit endpoints for the sake of this example. Valid deposit message are supposed to be an ERC20 that exists in the Registrar contract’s approved tokens list. It looks like this:

function depositERC20(
    AccountMessages.DepositRequest memory curDetails,
    address curTokenaddress,
    uint256 curAmount
) external;

As you can see we would need to pass along the amount to deposit, the token address of the deposit token, and a DepositRequest struct. That struct is rather simple and provides the Accounts contract further information about splits the user desires and which Endowment ID to credit the deposit to. It looks like this:

struct DepositRequest {
    uint256 id;
    uint256 lockedPercentage;
    uint256 liquidPercentage;
}

Placing Withdraws

⚠️ NOTE: All withdraws from an AST come out of the Liquid Balance of Tokens on Hand. Locked Withdraws are NOT allowed from ASTs until the maturity time has been reached, hence the name.

The shape of a withdraw message is as follows:

function withdraw(
    uint256 curId,
    AngelCoreStruct.AccountType acctType,
    address curBeneficiary,
    address[] memory curTokenaddress,
    uint256[] memory curAmount
)

In order to perform a withdraw:

1. An endowment member creates a transaction on the endowment multisig using the submitTransaction endpoint, with the destination address as the Accounts contract, a value set as 0 and the calldata for withdraw with liquid option.
2. Other endowment members sign the transaction on multisig identified by transaction id.
3. Once (n/2+1)[the default, unless changed] signers sign transaction, it can be executed. However, this will happen automatically if the require_execution is set to false in the multisig config.

Support Links & GitHub Repositiories

Support & Social Media Links

For additional support not covered in this documentation, please email support@angelprotocol.io or join us on our social & community channels:

• Twitter
• Telegram
• Discord
• YouTube
• LinkedIn

GitHub Repos

This documentation

See an error? Found a section lacking? Want to see a new area covered for your use case? Feel free to open an issue here for us to work on.

React Web App for Angel Protocol and Angel Giving

This is a useful repo to familiarize yourself using React JS components to manage wallet signing and interacting with our Angel Protocol smart contracts and AWS APIs. It can even be used to bootstrap your own site with minimal code changes need. More details on this coming soon!

Single page web app for Angel Protocol causes

This is a template repo that can be cloned and modified to setup a single-page web app for a donation page to your AST. It's best used for specific causes or themed fundraisers. Feel free to reach out on our Discord for more information about how we can help you get setup with and using this!

FAQs

General

Tokenized Assets (Web3, Crypto, Blockchain)

Polygon (Mumbai) - Contracts and Wallets

Contract Addresses

Registrar

• registrarImplementation: 0xD0DF2E81A44A8d5191C4Aaba74B1fA6b1429F729
• registrarProxy: 0xf9ae9FEb01B382C87d391F04a021fae312264CA

Accounts

• diamond: 0xf725Ff6235D53dA06Acb4a70AA33206a1447D55

EndowmentMultiSigAddress

• EndowmentMultiSigEmitterProxy: 0xC0c1d1659f88c0D0737069354b93874cBebfdfD7
• EndowmentMultiSigEmitterImplementation: 0x6472BC08F58D989483665F8Da7999516Ec7dF489
• MultiSigWalletFactory: 0x59802CEB7B8af8F0619A74Db0fC70e880ca9f47D
• MultiSigWalletImplementation: 0x7D8F4C57582abBbfa977541d740908b983A3952

Tokens

• USDC: 0xaBCe32FBA4C591E8Ea5A5f711F7112dC08BCee74
• Token: 0x06499E212Ce9F9D4a2147e82242F137c5e32f8C

Other MultiSigs (non-Endowment)

• ApplicationsMultiSigProxy: 0x1edC050B5d84cbB0cA0b56356f3F7307efcd50Fb
• APTeamMultiSigProxy: 0xC26Ac43b14ebCbff5029792052aF3e4DF3233902
• ApplicationMultisigImplementation: 0x4bCbb6eec52d710e0f699Fe5f4D4920E0627B6C1
• APTeamMultisigImplementation: 0x308AD7B20A0070D848a551E70C7C47d0e9673DA

Charity Application

• CharityApplicationProxy: 0x3516F641df05537a903D655844736eE991E69902
• CharityApplicationImplementation: 0xB5c18b5A3a5E325f25133Df7D026E9fC47F235a

Swap Router

• swapRouterProxy: 0x0c00F32a3603ba39f6D1eACD21a0D60d2c58675c
• swapRouterImplementation: 0x430E6044d849f6506F36d2A50Ce41924E559EbD

Index Fund

• indexFundProxy: 0xba4A7987e34BFDCb1D10e1318934dBce1024bDC8
• indexFundImplementation: 0xc8C19c0cc539F827BDD6CAF216bf6f3EB1166bD

SubDao Emitter

• SubdaoEmitterProxyAddress: 0x026Db89632da750c0b2C136253208262A680E527
• SubdaoEmitterImplementationAddress: 0xa145F2fDC3e2774C70Dc247d804986C91e878d4

Halo Implementations

• DonationMatchImplementation: 0xDfE663881Dd23d4B0d32899fE43E6347F21fF41f

Donation Match

• DonationMatchProxy: 0x8ead0CF0f28a0dF2de0Ac7cFEB1b48dB20619cD7
• DonationMatchImplementation: 0x89831907835e537Be7818b692482B39815C55FE

SubDao

• subDaoImplementation: 0x10618938dFD69dA98eB5f4112a4487fAC6b22ef7
• subDaoERC20Implementation: 0x25E2c69e9775bA8d2c0a38b3212987123b8727eF
• subDaoCurveTokenImplementation: 0xBdf1fFA5B0357744DE7517d98aDf8dC22c1eF373
• IncentivisedVotingLockupImplementation: 0x0c7056652736A06d6D90f11B29176DEa7630f14

Wallet Addresses

None to note at this time