diff --git a/docs/encyclopedia/clawbacks.mdx b/docs/encyclopedia/clawbacks.mdx
index 587b463d3..e1e986e16 100644
--- a/docs/encyclopedia/clawbacks.mdx
+++ b/docs/encyclopedia/clawbacks.mdx
@@ -2,6 +2,8 @@
title: Clawbacks
---
+import { CodeExample } from "@site/src/components/CodeExample"
+
Clawbacks were introduced in CAP-0035 and allow an asset issuer to burn a specific amount of a clawback-enabled asset from a trustline or claimable balance, effectively destroying it and removing it from a recipient’s balance.
They were designed to allow asset issuers to meet securities regulations, which in many jurisdictions require asset issuers (or designated transfer agents) to have the ability to revoke assets in the event of a mistaken or fraudulent transaction or other regulatory action regarding a specific person or asset.
@@ -45,22 +47,168 @@ Properly issuing an asset (with separate issuing and distribution accounts) is a
Also, note that we first need to enable clawbacks and then establish trustlines since you cannot retroactively enable clawback on existing trustlines.
-[insert code]
+
+
+```js
+const sdk = require("stellar-sdk");
+
+let server = new sdk.Server("https://horizon-testnet.stellar.org");
+
+const A = sdk.Keypair.fromSecret(
+ "SAQLZCQA6AYUXK6JSKVPJ2MZ5K5IIABJOEQIG4RVBHX4PG2KMRKWXCHJ",
+);
+const B = sdk.Keypair.fromSecret(
+ "SAAY2H7SANIS3JLFBFPLJRTYNLUYH4UTROIKRVFI4FEYV4LDW5Y7HDZ4",
+);
+const C = sdk.Keypair.fromSecret(
+ "SCZANGBA5YHTNYVVV4C3U252E2B6P6F5T3U6MM63WBSBZATAQI3EBTQ4",
+);
+
+const ASSET = new sdk.Asset("CLAW", A.publicKey());
+
+/// Enables AuthClawbackEnabledFlag on an account.
+function enableClawback(account, keys) {
+ return server.submitTransaction(
+ buildTx(account, keys, [
+ sdk.Operation.setOptions({
+ setFlags: sdk.AuthClawbackEnabledFlag | sdk.AuthRevocableFlag,
+ }),
+ ]),
+ );
+}
+
+/// Establishes a trustline for `recipient` for ASSET (from above).
+const establishTrustline = function (recipient, key) {
+ return server.submitTransaction(
+ buildTx(recipient, key, [
+ sdk.Operation.changeTrust({
+ asset: ASSET,
+ limit: "5000", // arbitrary
+ }),
+ ]),
+ );
+};
+
+/// Retrieves latest account info for all accounts.
+function getAccounts() {
+ return Promise.all([
+ server.loadAccount(A.publicKey()),
+ server.loadAccount(B.publicKey()),
+ server.loadAccount(C.publicKey()),
+ ]);
+}
+
+/// Enables clawback on A, and establishes trustlines from C, B -> A.
+function preamble() {
+ return getAccounts().then(function (accounts) {
+ let [accountA, accountB, accountC] = accounts;
+ return enableClawback(accountA, A).then(
+ Promise.all([
+ establishTrustline(accountB, B),
+ establishTrustline(accountC, C),
+ ]),
+ );
+ });
+}
+
+/// Helps simplify creating & signing a transaction.
+function buildTx(source, signer, ops) {
+ var tx = new StellarSdk.TransactionBuilder(source, {
+ fee: 100,
+ networkPassphrase: StellarSdk.Networks.TESTNET,
+ });
+ ops.forEach((op) => tx.addOperation(op));
+ tx = tx.setTimeout(30).build();
+ tx.sign(signer);
+ return tx;
+}
+
+/// Prints the balances of a list of accounts.
+function showBalances(accounts) {
+ accounts.forEach((acc) => {
+ console.log(`${acc.accountId().substring(0, 5)}: ${getBalance(acc)}`);
+ });
+}
+```
+
+
### Example 1: Payments
With the shared setup code out of the way, we can now demonstrate how clawback works for payments. This example will highlight how the asset issuer holds control over their asset regardless of how it gets distributed to the world.
In our scenario, Account A will pay Account B with 1000 tokens of its custom asset; then, B will pay Account C 500 tokens in turn. Finally, A will claw back half of C’s balance, burning 250 tokens forever. Let’s dive into the helper functions:
-[insert code]
+
+
+```js
+/// Make a payment to `toAccount` from `fromAccount` for `amount`.
+function makePayment(toAccount, fromAccount, fromKey, amount) {
+ return server.submitTransaction(
+ buildTx(fromAccount, fromKey, [
+ sdk.Operation.payment({
+ destination: toAccount.accountId(),
+ asset: ASSET, // defined in preamble
+ amount: amount,
+ }),
+ ]),
+ );
+}
+
+/// Perform a clawback by `byAccount` of `amount` from `fromAccount`.
+function doClawback(byAccount, byKey, fromAccount, amount) {
+ return server.submitTransaction(
+ buildTx(byAccount, byKey, [
+ sdk.Operation.clawback({
+ from: fromAccount.accountId(),
+ asset: ASSET, // defined in preamble
+ amount: amount,
+ }),
+ ]),
+ );
+}
+
+/// Retrieves the balance of ASSET in `account`.
+function getBalance(account) {
+ const balances = account.balances.filter((balance) => {
+ return (
+ balance.asset_code == ASSET.code && balance.asset_issuer == ASSET.issuer
+ );
+ });
+ return balances.length > 0 ? balances[0].balance : "0";
+}
+```
+
+
These snippets will help us with the final composition: making some payments to distribute the asset to the world and clawing some of it back.
-[insert code]
+
+
+```js
+function examplePaymentClawback() {
+ return getAccounts()
+ .then(function (accounts) {
+ let [accountA, accountB, accountC] = accounts;
+ return makePayment(accountB, accountA, A, "1000")
+ .then(makePayment(accountC, accountB, B, "500"))
+ .then(doClawback(accountA, A, accountC, "250"));
+ })
+ .then(getAccounts)
+ .then(showBalances);
+}
+
+preamble().then(examplePaymentClawback);
+```
+
+
After running our example, we should see the balances reflect the example flow:
-[insert code]
+```
+GCIHA: 0
+GDS5N: 500
+GC2BK: 250
+```
Notice that `GCIHA` (Account A, the issuer) holds none of the asset despite clawing back 250 from Account C. This should drive home the fact that clawed-back assets are burned, not transferred.
@@ -71,15 +219,72 @@ Direct payments aren’t the only way to transfer assets between accounts: claim
We need some additional helper methods to get started working efficiently with claimable balances:
-[insert code]
+
+
+```js
+function createClaimable(fromAccount, fromKey, toAccount, amount) {
+ return server.submitTransaction(
+ buildTx(fromAccount, fromKey, [
+ sdk.Operation.createClaimableBalance({
+ asset: ASSET,
+ amount: amount,
+ claimants: [new sdk.Claimant(toAccount.accountId())],
+ }),
+ ]),
+ );
+}
+
+// https://developers.stellar.org/docs/glossary/claimable-balance/#example
+function getBalanceId(txResponse) {
+ const txResult = sdk.xdr.TransactionResult.fromXDR(
+ txResponse.result_xdr,
+ "base64",
+ );
+ const operationResult = txResult.result().results()[0];
+
+ let creationResult = operationResult.value().createClaimableBalanceResult();
+ return creationResult.balanceId().toXDR("hex");
+}
+
+function clawbackClaimable(issuerAccount, issuerKey, balanceId) {
+ return server.submitTransaction(
+ buildTx(issuerAccount, issuerKey, [
+ sdk.Operation.clawbackClaimableBalance({ balanceId }),
+ ]),
+ );
+}
+```
+
+
Now, we can fulfill the flow: A pays B, who sends a claimable balance to C, who gets it clawed back by A. (Note that we rely on the `makePayment` helper from the earlier example.)
-[insert code]
+
+
+```js
+function exampleClaimableBalanceClawback() {
+ return getAccounts()
+ .then(function (accounts) {
+ let [accountA, accountB, accountC] = accounts;
+
+ return makePayment(accountB, accountA, A, "1000")
+ .then(() => createClaimable(accountB, B, accountC, "500"))
+ .then((txResp) => clawbackClaimable(accountA, A, getBalanceId(txResp)));
+ })
+ .then(getAccounts)
+ .then(showBalances);
+}
+```
+
+
After running `preamble().then(examplePaymentClawback)`, we should see the balances reflect our flow:
-[insert code]
+```
+GCIHA: 0
+GDS5N: 500
+GC2BK: 0
+```
### Example 3: Selectively Enabling Clawback
@@ -89,12 +294,97 @@ In the following example, we’ll have an account (Account A, as before) issue a
First, let’s prepare the accounts (note that we are relying here on helper functions defined in the earlier examples):
-[insert code]
+
+
+```js
+function getAccounts() {
+ return Promise.all([
+ server.loadAccount(A.publicKey()),
+ server.loadAccount(B.publicKey()),
+ ]);
+}
+
+function preambleRedux() {
+ return getAccounts().then((accounts) => {
+ return enableClawback(accounts[0], A).then(() =>
+ establishTrustline(accounts[1], B),
+ );
+ });
+}
+```
+
+
Now, let’s distribute some of our asset to Account B, just to claw it back. Then, we’ll clear the flag from the trustline and show that another clawback isn’t possible:
-[insert code]
+
+
+```js
+function disableClawback(issuerAccount, issuerKeys, forTrustor) {
+ return server.submitTransaction(
+ buildTx(issuerAccount, issuerKeys, [
+ sdk.Operation.setTrustLineFlags({
+ trustor: forTrustor.accountId(),
+ asset: ASSET, // defined in the (original) preamble
+ flags: {
+ clawbackEnabled: false,
+ },
+ }),
+ ]),
+ );
+}
+
+function exampleSelectiveClawback() {
+ return getAccounts()
+ .then((accounts) => {
+ let [accountA, accountB] = accounts;
+ return makePayment(accountB, accountA, A, "1000")
+ .then(getAccounts)
+ .then(showBalances)
+ .then(() => doClawback(accountA, A, accountB, "500"))
+ .then(getAccounts)
+ .then(showBalances)
+ .then(() => disableClawback(accountA, A, accountB))
+ .then(() => doClawback(accountA, A, accountB, "500"))
+ .catch((err) => {
+ if (err.response && err.response.data) {
+ // Note that this is a *very* specific way to check for an error, and
+ // you should probably never do it this way.
+ // We do this here to demonstrate that the clawback error *does*
+ // occur as expected.
+ const opErrors = err.response.data.extras.result_codes.operations;
+ if (
+ opErrors &&
+ opErrors.length > 0 &&
+ opErrors[0] === "op_no_clawback_enabled"
+ ) {
+ console.info("Clawback failed, as expected!");
+ } else {
+ console.error(
+ "Uh-oh, some other failure occurred:",
+ err.response.data.extras,
+ );
+ }
+ } else {
+ console.error("Uh-oh, unknown failure:", err);
+ }
+ });
+ })
+ .then(getAccounts)
+ .then(showBalances);
+}
+```
+
+
Run the example (e.g. `via preambleRedux().then(exampleSelectiveClawback)`) and observe its result:
-[insert code]
+```
+GCIHA: 0
+GDS5N: 1000
+GCIHA: 0
+GDS5N: 500
+Clawback failed, as expected!
+GCIHA: 0
+GDS5N: 500
+```
diff --git a/src/components/CodeExample.js b/src/components/CodeExample.js
index 71ef34e14..8d0393352 100644
--- a/src/components/CodeExample.js
+++ b/src/components/CodeExample.js
@@ -21,6 +21,8 @@ const CODE_LANGS = {
};
export const CodeExample = ({ children }) => (
+ // console.log(children),
+
{React.Children.map(children, (child, index) => {
const codeProps = child.props.children.props;