# Stellar Protocol 14 API in Horizon

This doc lists the changes to the Horizon API introduced by [CAP-23](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0023.md) and [CAP-33](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0033.md). These two CAPs comprise the public-facing changes in Stellar Protocol 14. The first Horizon version with the updated API is Horizon 1.9.0-RC, to be released 2020-09-21 ([monorepo release page](https://github.com/stellar/go/releases)).

This protocol upgrade is purely additive. We expect a protocol 14 compliant SDK to be able to run successfully against a protocol 13 network.

We are aiming for the following timeline:

- 2020-09-21 Horizon 1.9.0-RC is released with support for protocol 14
- 2020-09-30 Testnet will vote to update to protocol 14
- 2020-10-28 Pubnet will vote to update to protocol 14

In what follows, "canonical form" means `code:address` or `native` (for the XLM asset).

## New objects

* Claimable Balance with the following fields:
* `id` - balance ID,
* `paging_token` - paging token,
* `asset` - asset available to be claimed (in canonical form),
* `amount` - amount available to be claimed (string, like all amounts),
* `sponsor` - sponsoring account ID (can be `null`),
* `last_modified_ledger` - sequence number of the ledger when the balance was last modified,
* `claimants` - list of objects:
* `destination` - destination account ID,
* `predicate` - predicate required to claim a balance (see below).

## Modified objects

* [Account](https://developers.stellar.org/api/resources/accounts/object/) object:
* New `sponsor` field (account ID, can be `null`).
* New `num_sponsoring` field - number of reserves sponsored by this account,
* New `num_sponsored` field - number of reserves sponsored for this account.
* New `sponsor` field (account ID) in [Account](https://developers.stellar.org/api/resources/accounts/object/) > Balance object (only for non-native assets, can be `null`).
* New `sponsor` field (account ID) in [Account](https://developers.stellar.org/api/resources/accounts/object/) > Signers object (can be `null`).
* New `sponsor` field (account ID) in [Account's Data](https://developers.stellar.org/api/resources/accounts/data/) object (can be `null`).
* New `sponsor` field (account ID) in [Offer](https://developers.stellar.org/api/resources/offers/object/) object (can be `null`).

## New endpoints

* `/claimable_balances` - the list of Claimable Balance objects with the following parameters (only one param per request allowed):
* `asset` - find all claimable balances with the given asset (in canonical form),
* `claimant` - find all claimable balances with the given claimant account ID,
* `sponsor` - find all claimable balances sponsored by a given sponsor account ID.
* `/claimable_balances/{id}` - a single Claimable Balance object.

## Modified endpoints

* `/accounts` can now by filtered by `sponsor` (new GET param).
* `/offers` can now by filtered by `sponsor` (new GET param).

## New operations

* `create_claimable_balance` with the following fields:
* `asset` - asset available to be claimed (in canonical form),
* `amount` - amount available to be claimed,
* `claimants` - list of claimants with predicates (see below):
* `destination` - destination account ID,
* `predicate` - predicate required to claim a balance (see below).
* `claim_claimable_balance` with the following fields:
* `balance_id` - unique ID of balance to be claimed,
* `claimant` - account ID of a claimant.
* `begin_sponsoring_future_reserves` with the following fields:
* `sponsored_id` - account ID for which future reserves will be sponsored.
* `end_sponsoring_future_reserves` with the following fields:
* `begin_sponsor` - account sponsoring reserves.
* `revoke_sponsorship` with the following fields:
* `account_id` - if account sponsorship was revoked,
* `claimable_balance_id` - if claimable balance sponsorship was revoked,
* `data_account_id` - if account data sponsorship was revoked,
* `data_name` - if account data sponsorship was revoked,
* `offer_id` - if offer sponsorship was revoked,
* `trustline_account_id` - if trustline sponsorship was revoked,
* `trustline_asset` - if trustline sponsorship was revoked,
* `signer_account_id` - if signer sponsorship was revoked,
* `signer_key` - if signer sponsorship was revoked.

## New effects

* `claimable_balance_created` with the following fields:
* `balance_id` - unique ID of claimable balance,
* `asset` - asset available to be claimed (in canonical form),
* `amount` - amount available to be claimed.
* `claimable_balance_claimant_created` with the following fields:
* `balance_id` - unique ID of a claimable balance,
* `asset` - asset available to be claimed (in canonical form),
* `amount` - amount available to be claimed,
* `predicate` - predicate required to claim a balance (see below).
* `claimable_balance_claimed` with the following fields:
* `balance_id` - unique ID of a claimable balance,
* `asset` - asset available to be claimed (in canonical form),
* `amount` - amount available to be claimed,
* `account_sponsorship_created` with the following fields:
* `sponsor` - sponsor of an account.
* `account_sponsorship_updated` with the following fields:
* `new_sponsor` - new sponsor of an account,
* `former_sponsor` - former sponsor of an account.
* `account_sponsorship_removed` with the following fields:
* `former_sponsor` - former sponsor of an account.
* `trustline_sponsorship_created` with the following fields:
* `sponsor` - sponsor of a trustline.
* `trustline_sponsorship_updated` with the following fields:
* `new_sponsor` - new sponsor of a trustline,
* `former_sponsor` - former sponsor of a trustline.
* `trustline_sponsorship_removed` with the following fields:
* `former_sponsor` - former sponsor of a trustline.
* `claimable_balance_sponsorship_created` with the following fields:
* `sponsor` - sponsor of a claimable balance.
* `claimable_balance_sponsorship_updated` with the following fields:
* `new_sponsor` - new sponsor of a claimable balance,
* `former_sponsor` - former sponsor of a claimable balance.
* `claimable_balance_sponsorship_removed` with the following fields:
* `former_sponsor` - former sponsor of a claimable balance.
* `signer_sponsorship_created` with the following fields:
* `signer` - signer being sponsored.
* `sponsor` - signer sponsor.
* `signer_sponsorship_updated` with the following fields:
* `signer` - signer being sponsored.
* `former_sponsor` - the former sponsor of the signer.
* `new_sponsor` - the new sponsor of the signer.
* `signer_sponsorship_removed` with the following fields:
* `former_sponsor` - former sponsor of a signer.

## `predicate` field

`predicate` field is a JSON representation of `xdr.ClaimPredicate` as defined in [CAP-23](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0023.md) and is a requirement that needs to be satisfied to claim the balance. It is a recursive structure that can be represented in JSON using for example the following Golang struct:

type claimPredicateJSON struct {
	And           *[]claimPredicateJSON `json:"and,omitempty"`
	Or            *[]claimPredicateJSON `json:"or,omitempty"`
	Not           *claimPredicateJSON   `json:"not,omitempty"`
	Unconditional bool                  `json:"unconditional,omitempty"`
	AbsBefore     *time.Time            `json:"absBefore,omitempty"`
	RelBefore     *int64                `json:"relBefore,omitempty"`
}

Please refer to the [Golang implementation](https://github.com/stellar/go/blob/073878d8fdf435a000fd56932ec00fcd04c09b99/xdr/json.go) for details.

The following issue shows how the Golang SDK will handle predicate creation: https://github.com/stellar/go/issues/3000

## `RevokeSponsorshipOp`

The `RevokeSponsorshipOp` requires users to build `LedgerKey` or a `struct` for signers sponsorship. Ideally SDKs should expose helpers that build a valid operation for users without require them to pass an XDR LedgerKey. See the following issue for more information https://github.com/stellar/go/issues/3001