- An NFT with Huff, using polynomials over a finite field of the largest 20-byte prime, instead of mappings.
+ An NFT with Huff, using polynomials over a finite field of order the largest prime address, instead of mappings.
@@ -16,7 +16,9 @@
-`huffd1` is a non-fungible token implementation in Huff, where the ownership of a token is given by the evaluation of a polynomial $P(x)$, defined over the finite field of prime order $p = 2^{160} - 47$, the largest 160-bit prime:
+## Methodology
+
+`huffd1` is a non-fungible token implementation in Huff, where instead of ownership and approval mappings, we use polynomials $P[X]$ defined over the finite field of prime order $p = 2^{160} - 47$ that is the largest 160-bit prime:
$$
p = \mathtt{0xff}\ldots\mathtt{ffd1}
@@ -28,44 +30,25 @@ $$
P \in \mathbb{F}_{\mathtt{0xff}\ldots\mathtt{ffd1}}^{n-1}[X]
$$
-At contract deployment, all tokens are owned by the contract owner; and as a result the main polynomial is simply a constant polynomial equal to the owner address $P(x) = \mathtt{owner}$.
-
-To transfer a token, we simply have to find the difference between the sender and recipient addresses, multiply that value with the basis polynomial of the respective token, and add that to the main polynomial. See `transfer` subsection below for more details.
-
->
->
->
->
->
-> The stack comments are written in reverse order:
->
-> ```c
-> opcode // [top-N, ..., top-1, top]
-> pop // [top-N, ..., top-1]
-> 0x01 // [top-N, ..., top-1, 0x01]
-> ```
->
-> unlike the usual order described in the [Style Guide](https://docs.huff.sh/style-guide/overview/).
-
-## Usage
-
-Let's describe each function of [`huffd1`](./src/Huffd1.huff):
+Denote that ownership polynomial and approvals polynomial as $B[X]$ and $A[X]$ respectively. At contract deployment, all tokens are owned by the contract owner; and as a result the main polynomial is simply a constant polynomial equal to the owner address $P[X] = \mathtt{owner}$. There are also no approvals at first, so it is also a constant polynomial $A[X] = 0$.
-### `ownerOf`
+### Updating a Polynomial
-To find the owner of a token $t$, simply evaluate $P(t)$ and the result will be a 160-bit number corresponding to the owner address. We use [Horner's method](https://zcash.github.io/halo2/background/polynomials.html#aside-horners-rule) to efficiently evaluate our polynomial.
+In a mapping `A` we could access the value stored at `t` as `A[t]`. Now, with a polynomial $A$, we evaluate $A(t)$ to find the "stored" value. The trick is on how one would update a polynomial the same way one could update a mapping.
-Initially, all tokens are owned by the contract deployer, which can be represented by the constant polynomial that is equal to the owner address.
+We treat the polynomial as an interpolation over many Lagrange basis polynomials $L_0, L_1, \ldots, L_{T-1}$ over $T$ points (total supply), where $L_t[X]$ is defined as a polynomial that is equal to 1 at $t$ and 0 on all other points.
-### `balanceOf`
+To update $A(t)$ to any value, we can surgically remove the current evaluation, and replace it with our own using the Lagrange basis for that point $t$. For example, to replace $A(t) = n$ with $A(t) = m$ we do:
-To find the balance of an address, iterate over all tokens and call `ownerOf`, counting the number of matching addresses along the way.
+$$
+A[X] := A[X] + L_t[X](m - n)
+$$
-### `transfer`
+Note that since we are operating over a finite-field, multiplications will use `MULMOD` and additions will use `ADDMOD`. ALso note that $-a$ is obtained by $p-a$ where $p$ is the order of the finite field.
-To transfer a token $t$ from address $a \to b$, update $P(x)$ to be $P(x) + L_t(x)(b - a)$. Here, $L_t(x)$ is the Lagrange basis of the token, defined as a polynomial that is equal to 1 at $t$ and 0 on all other points. These polynomials are computed before deploying the contract, and are stored within the contract bytecode.
+### Storing the Basis Polynomials
-We have a [Sage script](./src/Huffd1.sage) that can export the basis polynomials, one for each token id, as a codetable where the coefficients of each polynomial are concatenated.
+The basis polynomials are computed before deploying the contract, and are stored within the contract bytecode. We have a [Sage script](./src/Huffd1.sage) that can export the basis polynomials, one for each token id, as a codetable where the coefficients of each polynomial are concatenated.
```c
// basis polynomials coefficients
@@ -74,10 +57,10 @@ We have a [Sage script](./src/Huffd1.sage) that can export the basis polynomials
}
// number of tokens
-#define constant TOTAL_SUPPLY = 0xa
+#define constant TOTAL_SUPPLY = 0xa // 10 tokens
// number of bytes per coefficient
-#define constant COEFF_SIZE = 0x14
+#define constant COEFF_SIZE = 0x14 // 20 bytes
// order of the finite field
#define constant ORDER = 0xffffffffffffffffffffffffffffffffffffffd1
@@ -92,17 +75,36 @@ Using these, we can load polynomials from the code table.
>
> The codetable grows pretty large for 20-byte coefficient size, and may easily get past the 24KB maximum contract size. To be more specific, for coefficient size `S` and total supply `N`, you will have `N` polynomials with `N` coefficients each, with `S` bytes per coefficient, resulting in total number of bytes of `N * N * S`.
-This operation results in multiplying the coefficients of $L_t(x)$ with $(b - a)$ which we will do via `MULMOD`, and afterwards summation of the coefficients of $P(x)$ and the resulting polynomial from previous step, using `ADDMOD`.
+### Evaluating the Polynomial
+
+We use [Horner's method](https://zcash.github.io/halo2/background/polynomials.html#aside-horners-rule) to efficiently evaluate our polynomial. With this method, instead of:
+
+$$
+a_0 + a_1X + a_2X^2 + \ldots a_{T-1}X^{T-1}
+$$
+
+we do:
+
+$$
+a_0 + X(a_1 + X(a_2 + \ldots + X(a_{T_2} + Xa_{T-1}))
+$$
-Also note that $-a$ is obtained by $p-a$ where $p$ is the order of the finite field.
+which also plays nicely with the reverse coefficient form that we use to store the polynomials.
-### `name`
+## Usage
-Returns the string `"Huffd1"`.
+[`huffd1`](./src/Huffd1.huff) implements the following methods:
-### `symbol`
+- `name`: returns the string `"Huffd1"`.
+- `symbol`: returns the string `"FFD1"`.
+- `ownerOf`: evaluates $B[X]$ at the given token id `t`.
+- `balanceOf`: evaluates $B[X]$ over all token ids, counting the matching addresses along the way (beware of gas).
+- `transfer`: updates $B[X]$ with the new address.
+- `transferFrom`: updates $B[X]$ with the new address.
+- `approve`: updates $A[X]$ with the new address.
+- `getApproved`: evaluates $A[X]$ at the given token id `t`.
-Returns the string `"FFD1"`.
+It also includes ownership stuff in [`Owned.huff`](./src/util/Owned.huff) imported from [Huffmate](https://github.com/huff-language/huffmate/blob/main/src/auth/Owned.huff). Polynomial operations are implemented under [`Polynomial.huff`](./src/util/Polynomial.huff).
## Testing
@@ -119,14 +121,25 @@ forge t -vvv --mc Huffd1
I use `-vvv` to see reverts in detail.
+>
+>
+>
+>
+>
+> The stack comments are written in reverse order:
+>
+> ```c
+> opcode // [top-N, ..., top-1, top]
+> pop // [top-N, ..., top-1]
+> 0x01 // [top-N, ..., top-1, 0x01]
+> ```
+>
+> unlike the usual order described in the [Style Guide](https://docs.huff.sh/style-guide/overview/).
+
## Remarks
- This project was done for the [Huff hackathon](https://huff.sh/hackathon)!
-- This is a very inefficient contract both in contract size and gas usage, and was done mostly for the nerd-snipability factors of using polynomials instead of mappings.
-
-- We can implement approvals with another polynomial too, but time did not permit. Also, there are many optimizations to do in many different places within the code.
-
- We could also use $p = 2^{160} + 7$, but I wanted all coefficients to be strictly 160-bits, which is not the case with that prime. In fact, the concept works for any prime order, but we would like to use an order that can fit almost all the addresses while being as large as an address.
- Maybe use foundry FFI to generate the basis polynomials during contract creation?
->